Merge branch 'upstream' into dielectric-updates

.github/CODEOWNERS

@@ -13,40 +13,45 @@ lib/kim/*             @ellio167
 lib/mesont/*          @iafoss
 
 # whole packages
+src/ADIOS/*           @pnorbert
 src/AMOEBA/*          @sjplimp
-src/COMPRESS/*        @rbberger
+src/BPM/*             @jtclemm
-src/GPU/*             @ndtrung81
-src/KOKKOS/*          @stanmoore1
-src/KIM/*             @ellio167
-src/LATTE/*           @cnegre
-src/MLIAP/*           @athomps
-src/SNAP/*            @athomps
-src/SPIN/*            @julient31
 src/BROWNIAN/*        @samueljmcameron
 src/CG-DNA/*          @ohenrich
 src/CG-SPICA/*        @yskmiyazaki
 src/COLVARS/*         @giacomofiorin
+src/COMPRESS/*        @rbberger
 src/DIELECTRIC/*      @ndtrung81
 src/ELECTRODE/*       @ludwig-ahrens
 src/FEP/*             @agiliopadua
-src/ML-HDNNP/*        @singraber
+src/GPU/*             @ndtrung81
+src/GRANULAR/*        @jtclemm @dsbolin
 src/INTEL/*           @wmbrownintel
+src/KIM/*             @ellio167
+src/KOKKOS/*          @stanmoore1
+src/LATTE/*           @cnegre
 src/MANIFOLD/*        @Pakketeretet2
-src/MDI/*             @taylor-a-barnes
+src/MDI/*             @taylor-a-barnes @sjplimp
 src/MEAM/*            @martok
 src/MESONT/*          @iafoss
+src/ML-HDNNP/*        @singraber
+src/ML-IAP/*          @athomps
+src/ML-PACE/*         @yury-lysogorskiy
+src/ML-POD/*          @exapde @rohskopf
 src/MOFFF/*           @hheenen
 src/MOLFILE/*         @akohlmey
 src/NETCDF/*          @pastewka
-src/ML-PACE/*         @yury-lysogorskiy
-src/PLUMED/*          @gtribello
-src/PHONON/*          @lingtikong
-src/PTM/*             @pmla
 src/OPENMP/*          @akohlmey
+src/PHONON/*          @lingtikong
+src/PLUGIN/*          @akohlmey
+src/PLUMED/*          @gtribello
+src/PTM/*             @pmla
 src/QMMM/*            @akohlmey
-src/REAXFF/*          @hasanmetin @stanmoore1
 src/REACTION/*        @jrgissing
+src/REAXFF/*          @hasanmetin @stanmoore1
 src/SCAFACOS/*        @rhalver
+src/SNAP/*            @athomps
+src/SPIN/*            @julient31
 src/TALLY/*           @akohlmey
 src/UEF/*             @danicholson
 src/VTK/*             @rbberger
@@ -59,6 +64,8 @@ src/MANYBODY/pair_atm.*             @sergeylishchuk
 src/REPLICA/*_grem.*                @dstelter92
 src/EXTRA-COMPUTE/compute_stress_mop*.* @RomainVermorel
 src/MISC/*_tracker.*                @jtclemm
+src/MC/fix_gcmc.*                   @athomps
+src/MC/fix_sgcmc.*                  @athomps
 
 # core LAMMPS classes
 src/lammps.*              @sjplimp
@@ -120,27 +127,32 @@ src/dump_movie.*          @akohlmey
 src/exceptions.h          @rbberger
 src/fix_nh.*              @athomps
 src/info.*                @akohlmey @rbberger
-src/timer.*               @akohlmey
 src/min*                  @sjplimp @stanmoore1
+src/platform.*            @akohlmey
+src/timer.*               @akohlmey
 src/utils.*               @akohlmey @rbberger
 src/verlet.*              @sjplimp @stanmoore1
 src/math_eigen_impl.h     @jewettaij
 
 # tools
-tools/msi2lmp/*       @akohlmey
+tools/coding_standard/* @akohlmey @rbberger
 tools/emacs/*         @HaoZeke
-tools/singularity/*   @akohlmey @rbberger
+tools/lammps-shell/*  @akohlmey
-tools/coding_standard/* @rbberger
+tools/msi2lmp/*       @akohlmey
-tools/valgrind/*      @akohlmey
-tools/swig/*          @akohlmey
 tools/offline/*       @rbberger
+tools/singularity/*   @akohlmey @rbberger
+tools/swig/*          @akohlmey
+tools/valgrind/*      @akohlmey
 tools/vim/*           @hammondkd
 
 # tests
-unittest/*            @akohlmey @rbberger
+unittest/*            @akohlmey
 
 # cmake
 cmake/*               @junghans @rbberger
+cmake/Modules/LAMMPSInterfacePlugin.cmake @akohlmey
+cmake/Modules/MPI4WIN.cmake @akohlmey
+cmake/Modules/OpenCLLoader.cmake @akohlmey
 cmake/Modules/Packages/COLVARS.cmake @junghans @rbberger @giacomofiorin
 cmake/Modules/Packages/KIM.cmake @junghans @rbberger @ellio167
 cmake/presets/*.cmake @akohlmey
@@ -149,13 +161,12 @@ cmake/presets/*.cmake @akohlmey
 python/*              @rbberger
 
 # fortran
-fortran/*             @akohlmey
+fortran/*             @akohlmey @hammondkd
 
 # docs
-doc/utils/*/*         @rbberger
+doc/*                 @akohlmey
-doc/Makefile          @rbberger
-doc/README            @rbberger
 examples/plugin/*     @akohlmey
+examples/PACKAGES/pace/plugin/*     @akohlmey
 
 # for releases
 src/version.h         @sjplimp

.github/ISSUE_TEMPLATE/help_request.md

@@ -1,6 +1,6 @@
 ---
 name: Request for Help
-about: "Don't post help requests here, email the lammps-users mailing list"
+about: "Don't post help requests here, post in the LAMMPS forum"
 title: ""
 labels: invalid
 assignees: ''
@@ -8,8 +8,9 @@ assignees: ''
 ---
 
 Please **do not** post requests for help (e.g. with installing or using LAMMPS) here.
-Instead send an e-mail to the lammps-users mailing list.
+Instead, you can post to the LAMMPS category in the Materials Science Community
+Discourse forum at: https://matsci.org/lammps/
 
 This issue tracker is for tracking LAMMPS development related issues only.
 
-Thanks for your cooperation.
+Thank you in advance for your cooperation.

.github/workflows/compile-msvc.yml

@@ -26,15 +26,19 @@ jobs:
     - name: Select Python version
       uses: actions/setup-python@v4
       with:
-        python-version: '3.10'
+        python-version: '3.11'
 
     - name: Building LAMMPS via CMake
       shell: bash
       run: |
         python3 -m pip install numpy
         python3 -m pip install pyyaml
+        nuget install MSMPIsdk
+        nuget install MSMPIDIST
         cmake -C cmake/presets/windows.cmake \
               -D PKG_PYTHON=on \
+              -D WITH_PNG=off \
+              -D WITH_JPEG=off \
               -S cmake -B build \
               -D BUILD_SHARED_LIBS=on \
               -D LAMMPS_EXCEPTIONS=on \
@@ -50,4 +54,4 @@ jobs:
     - name: Run Unit Tests
       working-directory: build
       shell: bash
-      run: ctest -V -C Release
+      run: ctest -V -C Release -E FixTimestep:python_move_nve

README

@@ -16,8 +16,8 @@ National Laboratories, a US Department of Energy facility, with
 funding from the DOE.  It is an open-source code, distributed freely
 under the terms of the GNU Public License (GPL) version 2.
 
-The primary author of the code is Steve Plimpton, who can be emailed
+The code is maintained by the LAMMPS development team who can be emailed
-at sjplimp@sandia.gov.  The LAMMPS WWW Site at www.lammps.org has
+at developers@lammps.org.  The LAMMPS WWW Site at www.lammps.org has
 more information about the code and its uses.
 
 The LAMMPS distribution includes the following files and directories:

cmake/CMakeLists.txt

@@ -7,6 +7,10 @@ cmake_minimum_required(VERSION 3.10)
 if(POLICY CMP0074)
   cmake_policy(SET CMP0074 NEW)
 endif()
+# set policy to silence warnings about ignoring  ${CMAKE_REQUIRED_LIBRARIES} but use it
+if(POLICY CMP0075)
+  cmake_policy(SET CMP0075 NEW)
+endif()
 # set policy to silence warnings about missing executable permissions in
 # pythonx.y-config when cross-compiling. review occasionally if it may be set to NEW
 if(POLICY CMP0109)
@@ -262,6 +266,7 @@ set(STANDARD_PACKAGES
   ML-QUIP
   ML-RANN
   ML-SNAP
+  ML-POD
   MOFFF
   MOLECULE
   MOLFILE
@@ -312,6 +317,15 @@ if(PKG_ADIOS)
   # script that defines the MPI::MPI_C target
   enable_language(C)
   find_package(ADIOS2 REQUIRED)
+  if(BUILD_MPI)
+    if(NOT ADIOS2_HAVE_MPI)
+      message(FATAL_ERROR "ADIOS2 must be built with MPI support when LAMMPS has MPI enabled")
+    endif()
+  else()
+    if(ADIOS2_HAVE_MPI)
+      message(FATAL_ERROR "ADIOS2 must be built without MPI support when LAMMPS has MPI disabled")
+    endif()
+  endif()
   target_link_libraries(lammps PRIVATE adios2::adios2)
 endif()
 
@@ -385,9 +399,9 @@ pkg_depends(EXTRA-MOLECULE MOLECULE)
 
 # detect if we may enable OpenMP support by default
 set(BUILD_OMP_DEFAULT OFF)
-find_package(OpenMP QUIET)
+find_package(OpenMP COMPONENTS CXX QUIET)
-if(OpenMP_FOUND)
+if(OpenMP_CXX_FOUND)
-  check_include_file_cxx(omp.h HAVE_OMP_H_INCLUDE)
+  check_omp_h_include()
   if(HAVE_OMP_H_INCLUDE)
     set(BUILD_OMP_DEFAULT ON)
   endif()
@@ -396,8 +410,8 @@ endif()
 option(BUILD_OMP "Build with OpenMP support" ${BUILD_OMP_DEFAULT})
 
 if(BUILD_OMP)
-  find_package(OpenMP REQUIRED)
+  find_package(OpenMP COMPONENTS CXX REQUIRED)
-  check_include_file_cxx(omp.h HAVE_OMP_H_INCLUDE)
+  check_omp_h_include()
   if(NOT HAVE_OMP_H_INCLUDE)
     message(FATAL_ERROR "Cannot find the 'omp.h' header file required for full OpenMP support")
   endif()
@@ -419,7 +433,7 @@ if(BUILD_OMP)
   target_link_libraries(lmp PRIVATE OpenMP::OpenMP_CXX)
 endif()
 
-if(PKG_MSCG OR PKG_ATC OR PKG_AWPMD OR PKG_ML-QUIP OR PKG_LATTE OR PKG_ELECTRODE)
+if(PKG_MSCG OR PKG_ATC OR PKG_AWPMD OR PKG_ML-QUIP OR PKG_ML-POD OR PKG_LATTE OR PKG_ELECTRODE)
   enable_language(C)
   if (NOT USE_INTERNAL_LINALG)
     find_package(LAPACK)
@@ -625,7 +639,7 @@ foreach(PKG_LIB POEMS ATC AWPMD H5MD MESONT)
   endif()
 endforeach()
 
-if(PKG_ELECTRODE)
+if(PKG_ELECTRODE OR PKG_ML-POD)
   target_link_libraries(lammps PRIVATE ${LAPACK_LIBRARIES})
 endif()
 
@@ -654,7 +668,7 @@ endif()
 # packages which selectively include variants based on enabled styles
 # e.g. accelerator packages
 ######################################################################
-foreach(PKG_WITH_INCL CORESHELL DPD-SMOOTH MISC PHONON QEQ OPENMP KOKKOS OPT INTEL GPU)
+foreach(PKG_WITH_INCL CORESHELL DPD-SMOOTH MC MISC PHONON QEQ OPENMP KOKKOS OPT INTEL GPU)
   if(PKG_${PKG_WITH_INCL})
     include(Packages/${PKG_WITH_INCL})
   endif()
@@ -727,18 +741,17 @@ list(FIND LANGUAGES "Fortran" _index)
 if(_index GREATER -1)
   target_link_libraries(lammps PRIVATE ${CMAKE_Fortran_IMPLICIT_LINK_LIBRARIES})
 endif()
-set(LAMMPS_CXX_HEADERS angle.h atom.h bond.h citeme.h comm.h compute.h dihedral.h domain.h error.h fix.h force.h group.h improper.h
+set(LAMMPS_CXX_HEADERS angle.h atom.h bond.h citeme.h comm.h command.h compute.h dihedral.h domain.h
-  input.h info.h kspace.h lammps.h lattice.h library.h lmppython.h lmptype.h memory.h modify.h neighbor.h neigh_list.h output.h
+  error.h exceptions.h fix.h force.h group.h improper.h input.h info.h kspace.h lammps.h lattice.h
-  pair.h pointers.h region.h timer.h universe.h update.h utils.h variable.h)
+  library.h lmppython.h lmptype.h memory.h modify.h neighbor.h neigh_list.h output.h pair.h
-if(LAMMPS_EXCEPTIONS)
+  platform.h pointers.h region.h timer.h universe.h update.h utils.h variable.h)
-  list(APPEND LAMMPS_CXX_HEADERS exceptions.h)
+set(LAMMPS_FMT_HEADERS core.h format.h)
-endif()
 
 set_target_properties(lammps PROPERTIES OUTPUT_NAME lammps${LAMMPS_MACHINE})
 set_target_properties(lammps PROPERTIES SOVERSION ${SOVERSION})
 set_target_properties(lammps PROPERTIES PREFIX "lib")
 target_include_directories(lammps PUBLIC $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}/lammps>)
-file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/includes/lammps)
+file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/includes/lammps ${CMAKE_CURRENT_BINARY_DIR}/includes/lammps/fmt)
 foreach(_HEADER ${LAMMPS_CXX_HEADERS})
   add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/includes/lammps/${_HEADER} COMMAND ${CMAKE_COMMAND} -E copy_if_different ${LAMMPS_SOURCE_DIR}/${_HEADER} ${CMAKE_CURRENT_BINARY_DIR}/includes/lammps/${_HEADER} DEPENDS ${LAMMPS_SOURCE_DIR}/${_HEADER})
   add_custom_target(${_HEADER} DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/includes/lammps/${_HEADER})
@@ -747,6 +760,14 @@ foreach(_HEADER ${LAMMPS_CXX_HEADERS})
     install(FILES ${LAMMPS_SOURCE_DIR}/${_HEADER} DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/lammps)
   endif()
 endforeach()
+foreach(_HEADER ${LAMMPS_FMT_HEADERS})
+  add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/includes/lammps/fmt/${_HEADER} COMMAND ${CMAKE_COMMAND} -E copy_if_different ${LAMMPS_SOURCE_DIR}/fmt/${_HEADER} ${CMAKE_CURRENT_BINARY_DIR}/includes/lammps/fmt/${_HEADER} DEPENDS ${LAMMPS_SOURCE_DIR}/fmt/${_HEADER})
+  add_custom_target(fmt_${_HEADER} DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/includes/lammps/fmt/${_HEADER})
+  add_dependencies(lammps fmt_${_HEADER})
+  if(BUILD_SHARED_LIBS)
+    install(FILES ${LAMMPS_SOURCE_DIR}/fmt/${_HEADER} DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/lammps/fmt)
+  endif()
+endforeach()
 target_include_directories(lammps INTERFACE $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/includes>)
 add_library(LAMMPS::lammps ALIAS lammps)
 get_target_property(LAMMPS_DEFINES lammps INTERFACE_COMPILE_DEFINITIONS)
@@ -969,9 +990,6 @@ if(PKG_GPU)
   endif()
   message(STATUS "GPU precision:            ${GPU_PREC}")
 endif()
-if(PKG_KOKKOS)
-  message(STATUS "Kokkos Arch: ${KOKKOS_ARCH}")
-endif()
 if(PKG_KSPACE)
   message(STATUS "<<< FFT settings >>>
 -- Primary FFT lib:  ${FFT}")

cmake/Modules/FindClangFormat.cmake

@@ -1,5 +1,10 @@
 # Find clang-format
 find_program(ClangFormat_EXECUTABLE NAMES clang-format
+                                          clang-format-15.0
+                                          clang-format-14.0
+                                          clang-format-13.0
+                                          clang-format-12.0
+                                          clang-format-11.0
                                           clang-format-10.0
                                           clang-format-9.0
                                           clang-format-8.0
@@ -14,19 +19,27 @@ if(ClangFormat_EXECUTABLE)
                   OUTPUT_VARIABLE clang_format_version
                   ERROR_QUIET OUTPUT_STRIP_TRAILING_WHITESPACE)
 
-
+  if(clang_format_version MATCHES "^(Ubuntu |)clang-format version .*")
-  if(clang_format_version MATCHES "^clang-format version .*")
+    # Arch Linux output:
-    # Arch Linux
     # clang-format version 10.0.0
-
+    #
-    # Ubuntu 18.04 LTS Output
+    # Ubuntu 18.04 LTS output:
     # clang-format version 6.0.0-1ubuntu2 (tags/RELEASE_600/final)
-    string(REGEX REPLACE "clang-format version ([0-9.]+).*"
+    #
-                         "\\1"
+    # Ubuntu 20.04 LTS output:
+    # clang-format version 10.0.0-4ubuntu1
+    #
+    # Ubuntu 22.04 LTS output:
+    # Ubuntu clang-format version 14.0.0-1ubuntu1
+    #
+    # Fedora 36 output:
+    # clang-format version 14.0.5 (Fedora 14.0.5-1.fc36)
+    string(REGEX REPLACE "^(Ubuntu |)clang-format version ([0-9.]+).*"
+                         "\\2"
                          ClangFormat_VERSION
                          "${clang_format_version}")
   elseif(clang_format_version MATCHES ".*LLVM version .*")
-    # CentOS 7 Output
+    # CentOS 7 output:
     # LLVM (http://llvm.org/):
     #   LLVM version 3.4.2
     #   Optimized build.

cmake/Modules/FindCythonize.cmake

@@ -22,7 +22,7 @@ endif()
 if(Python_EXECUTABLE)
   get_filename_component(_python_path ${Python_EXECUTABLE} PATH)
   find_program(Cythonize_EXECUTABLE
-    NAMES cythonize3 cythonize cythonize.bat
+    NAMES cythonize-${Python_VERSION_MAJOR}.${Python_VERSION_MINOR} cythonize3 cythonize cythonize.bat
     HINTS ${_python_path})
 endif()
 

cmake/Modules/FindZMQ.cmake

@@ -1,19 +0,0 @@
-find_path(ZMQ_INCLUDE_DIR zmq.h)
-find_library(ZMQ_LIBRARY NAMES zmq)
-
-include(FindPackageHandleStandardArgs)
-find_package_handle_standard_args(ZMQ DEFAULT_MSG ZMQ_LIBRARY ZMQ_INCLUDE_DIR)
-
-# Copy the results to the output variables and target.
-if(ZMQ_FOUND)
-  set(ZMQ_LIBRARIES ${ZMQ_LIBRARY})
-  set(ZMQ_INCLUDE_DIRS ${ZMQ_INCLUDE_DIR})
-
-  if(NOT TARGET ZMQ::ZMQ)
-    add_library(ZMQ::ZMQ UNKNOWN IMPORTED)
-    set_target_properties(ZMQ::ZMQ PROPERTIES
-      IMPORTED_LINK_INTERFACE_LANGUAGES "C"
-      IMPORTED_LOCATION "${ZMQ_LIBRARY}"
-      INTERFACE_INCLUDE_DIRECTORIES "${ZMQ_INCLUDE_DIR}")
-  endif()
-endif()

cmake/Modules/LAMMPSInterfacePlugin.cmake

@@ -112,45 +112,76 @@ 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 custom MPICH files for Windows
+    # Download and configure MinGW compatible MPICH development files for Windows
-    message(STATUS "Downloading and configuring MPICH-1.4.1 for Windows")
+    option(USE_MSMPI "Use Microsoft's MS-MPI SDK instead of MPICH2-1.4.1" OFF)
-    set(MPICH2_WIN64_DEVEL_URL "${LAMMPS_THIRDPARTY_URL}/mpich2-win64-devel.tar.gz" CACHE STRING "URL for MPICH2 (win64) tarball")
+    if(USE_MSMPI)
-    set(MPICH2_WIN32_DEVEL_URL "${LAMMPS_THIRDPARTY_URL}/mpich2-win32-devel.tar.gz" CACHE STRING "URL for MPICH2 (win32) tarball")
+      message(STATUS "Downloading and configuring MS-MPI 10.1 for Windows cross-compilation")
-    set(MPICH2_WIN64_DEVEL_MD5 "4939fdb59d13182fd5dd65211e469f14" CACHE STRING "MD5 checksum of MPICH2 (win64) tarball")
+      set(MPICH2_WIN64_DEVEL_URL "${LAMMPS_THIRDPARTY_URL}/msmpi-win64-devel.tar.gz" CACHE STRING "URL for MS-MPI (win64) tarball")
-    set(MPICH2_WIN32_DEVEL_MD5 "a61d153500dce44e21b755ee7257e031" CACHE STRING "MD5 checksum of MPICH2 (win32) 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_URL)
-    mark_as_advanced(MPICH2_WIN32_DEVEL_URL)
+      mark_as_advanced(MPICH2_WIN64_DEVEL_MD5)
-    mark_as_advanced(MPICH2_WIN64_DEVEL_MD5)
-    mark_as_advanced(MPICH2_WIN32_DEVEL_MD5)
 
-    include(ExternalProject)
+      include(ExternalProject)
-    if(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64")
+      if(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64")
-      ExternalProject_Add(mpi4win_build
+        ExternalProject_Add(mpi4win_build
-        URL     ${MPICH2_WIN64_DEVEL_URL}
+          URL     ${MPICH2_WIN64_DEVEL_URL}
-        URL_MD5 ${MPICH2_WIN64_DEVEL_MD5}
+          URL_MD5 ${MPICH2_WIN64_DEVEL_MD5}
-        CONFIGURE_COMMAND "" BUILD_COMMAND "" INSTALL_COMMAND ""
+          CONFIGURE_COMMAND "" BUILD_COMMAND "" INSTALL_COMMAND ""
-        BUILD_BYPRODUCTS <SOURCE_DIR>/lib/libmpi.a)
+          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")
     else()
-      ExternalProject_Add(mpi4win_build
+      # Download and configure custom MPICH files for Windows
-        URL     ${MPICH2_WIN32_DEVEL_URL}
+      message(STATUS "Downloading and configuring MPICH-1.4.1 for Windows")
-        URL_MD5 ${MPICH2_WIN32_DEVEL_MD5}
+      set(MPICH2_WIN64_DEVEL_URL "${LAMMPS_THIRDPARTY_URL}/mpich2-win64-devel.tar.gz" CACHE STRING "URL for MPICH2 (win64) tarball")
-        CONFIGURE_COMMAND "" BUILD_COMMAND "" INSTALL_COMMAND ""
+      set(MPICH2_WIN64_DEVEL_MD5 "4939fdb59d13182fd5dd65211e469f14" CACHE STRING "MD5 checksum of MPICH2 (win64) tarball")
-        BUILD_BYPRODUCTS <SOURCE_DIR>/lib/libmpi.a)
+      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")
     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")
   else()
     find_package(MPI REQUIRED)
     option(LAMMPS_LONGLONG_TO_LONG "Workaround if your system or MPI version does not recognize 'long long' data types" OFF)

cmake/Modules/LAMMPSUtils.cmake

@@ -24,6 +24,21 @@ function(validate_option name values)
     endif()
 endfunction(validate_option)
 
+# helper function to check for usable omp.h header
+function(check_omp_h_include)
+  find_package(OpenMP COMPONENTS CXX QUIET)
+  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})
+    set(CMAKE_REQUIRED_LIBRARIES ${OpenMP_CXX_LIBRARIES})
+    check_include_file_cxx(omp.h _have_omp_h)
+  else()
+    set(_have_omp_h FALSE)
+  endif()
+  set(HAVE_OMP_H_INCLUDE ${_have_omp_h} PARENT_SCOPE)
+endfunction()
+
 # helper function for getting the most recently modified file or folder from a glob pattern
 function(get_newest_file path variable)
   file(GLOB _dirs ${path})

cmake/Modules/MPI4WIN.cmake

@@ -1,39 +1,74 @@
-# Download and configure custom MPICH files for Windows
+# Download and configure MinGW compatible MPICH development files for Windows
-message(STATUS "Downloading and configuring MPICH-1.4.1 for Windows")
+option(USE_MSMPI "Use Microsoft's MS-MPI SDK instead of MPICH2-1.4.1" OFF)
-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(USE_MSMPI)
-if(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64")
+  message(STATUS "Downloading and configuring MS-MPI 10.1 for Windows cross-compilation")
-  ExternalProject_Add(mpi4win_build
+  set(MPICH2_WIN64_DEVEL_URL "${LAMMPS_THIRDPARTY_URL}/msmpi-win64-devel.tar.gz" CACHE STRING "URL for MS-MPI (win64) tarball")
-    URL     ${MPICH2_WIN64_DEVEL_URL}
+  set(MPICH2_WIN64_DEVEL_MD5 "86314daf1bffb809f1fcbefb8a547490" CACHE STRING "MD5 checksum of MS-MPI (win64) tarball")
-    URL_MD5 ${MPICH2_WIN64_DEVEL_MD5}
+  mark_as_advanced(MPICH2_WIN64_DEVEL_URL)
-    CONFIGURE_COMMAND "" BUILD_COMMAND "" INSTALL_COMMAND ""
+  mark_as_advanced(MPICH2_WIN64_DEVEL_MD5)
-    BUILD_BYPRODUCTS <SOURCE_DIR>/lib/libmpi.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(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")
 else()
-  ExternalProject_Add(mpi4win_build
+  message(STATUS "Downloading and configuring MPICH2-1.4.1 for Windows cross-compilation")
-    URL     ${MPICH2_WIN32_DEVEL_URL}
+  set(MPICH2_WIN64_DEVEL_URL "${LAMMPS_THIRDPARTY_URL}/mpich2-win64-devel.tar.gz" CACHE STRING "URL for MPICH2 (win64) tarball")
-    URL_MD5 ${MPICH2_WIN32_DEVEL_MD5}
+  set(MPICH2_WIN32_DEVEL_URL "${LAMMPS_THIRDPARTY_URL}/mpich2-win32-devel.tar.gz" CACHE STRING "URL for MPICH2 (win32) tarball")
-    CONFIGURE_COMMAND "" BUILD_COMMAND "" INSTALL_COMMAND ""
+  set(MPICH2_WIN64_DEVEL_MD5 "4939fdb59d13182fd5dd65211e469f14" CACHE STRING "MD5 checksum of MPICH2 (win64) tarball")
-    BUILD_BYPRODUCTS <SOURCE_DIR>/lib/libmpi.a)
+  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")
 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")

cmake/Modules/Packages/KOKKOS.cmake

@@ -15,8 +15,9 @@ if(Kokkos_ENABLE_OPENMP)
   if(NOT BUILD_OMP)
     message(FATAL_ERROR "Must enable BUILD_OMP with Kokkos_ENABLE_OPENMP")
   else()
-    if(LAMMPS_OMP_COMPAT_LEVEL LESS 4)
+    # NVHPC does not seem to provide a detectable OpenMP version, but is far beyond version 3.1
-      message(FATAL_ERROR "Compiler must support OpenMP 4.0 or later with Kokkos_ENABLE_OPENMP")
+    if((OpenMP_CXX_VERSION VERSION_LESS 3.1) AND NOT (CMAKE_CXX_COMPILER_ID STREQUAL "NVHPC"))
+      message(FATAL_ERROR "Compiler must support OpenMP 3.1 or later with Kokkos_ENABLE_OPENMP")
     endif()
   endif()
 endif()
@@ -123,7 +124,7 @@ set(KOKKOS_PKG_SOURCES ${KOKKOS_PKG_SOURCES_DIR}/kokkos.cpp
 
 if(PKG_KSPACE)
   list(APPEND KOKKOS_PKG_SOURCES ${KOKKOS_PKG_SOURCES_DIR}/fft3d_kokkos.cpp
-                                 ${KOKKOS_PKG_SOURCES_DIR}/gridcomm_kokkos.cpp
+                                 ${KOKKOS_PKG_SOURCES_DIR}/grid3d_kokkos.cpp
                                  ${KOKKOS_PKG_SOURCES_DIR}/remap_kokkos.cpp)
   if(Kokkos_ENABLE_CUDA)
     if(NOT (FFT STREQUAL "KISS"))
@@ -138,6 +139,12 @@ if(PKG_KSPACE)
   endif()
 endif()
 
+if(PKG_ML-IAP)
+  list(APPEND KOKKOS_PKG_SOURCES ${KOKKOS_PKG_SOURCES_DIR}/mliap_data_kokkos.cpp
+                                 ${KOKKOS_PKG_SOURCES_DIR}/mliap_descriptor_so3_kokkos.cpp
+                                 ${KOKKOS_PKG_SOURCES_DIR}/mliap_model_linear_kokkos.cpp
+                                 ${KOKKOS_PKG_SOURCES_DIR}/mliap_so3_kokkos.cpp)
+endif()
 
 if(PKG_PHONON)
   list(APPEND KOKKOS_PKG_SOURCES ${KOKKOS_PKG_SOURCES_DIR}/dynamical_matrix_kokkos.cpp)

cmake/Modules/Packages/MC.cmake

@@ -0,0 +1,9 @@
+# fix sgcmc may only be installed if also the EAM pair style from MANYBODY is installed
+if(NOT PKG_MANYBODY)
+  get_property(LAMMPS_FIX_HEADERS GLOBAL PROPERTY FIX)
+  list(REMOVE_ITEM LAMMPS_FIX_HEADERS ${LAMMPS_SOURCE_DIR}/MC/fix_sgcmc.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_sgcmc.cpp)
+  set_property(TARGET lammps PROPERTY SOURCES "${LAMMPS_SOURCES}")
+endif()

cmake/Modules/Packages/ML-IAP.cmake

@@ -2,7 +2,13 @@
 set(MLIAP_ENABLE_PYTHON_DEFAULT OFF)
 if(PKG_PYTHON)
   find_package(Cythonize QUIET)
-  if(Cythonize_FOUND)
+  if (CMAKE_VERSION VERSION_GREATER_EQUAL 3.14)
+    find_package(Python COMPONENTS NumPy QUIET)
+  else()
+    # assume we have NumPy
+    set(Python_NumPy_FOUND ON)
+  endif()
+  if(Cythonize_FOUND AND Python_NumPy_FOUND)
     set(MLIAP_ENABLE_PYTHON_DEFAULT ON)
   endif()
 endif()
@@ -11,6 +17,9 @@ option(MLIAP_ENABLE_PYTHON "Build ML-IAP package with Python support" ${MLIAP_EN
 
 if(MLIAP_ENABLE_PYTHON)
   find_package(Cythonize REQUIRED)
+  if (CMAKE_VERSION VERSION_GREATER_EQUAL 3.14)
+    find_package(Python COMPONENTS NumPy REQUIRED)
+  endif()
   if(NOT PKG_PYTHON)
     message(FATAL_ERROR "Must enable PYTHON package for including Python support in ML-IAP")
   endif()

cmake/Modules/Packages/ML-QUIP.cmake

@@ -58,12 +58,12 @@ if(DOWNLOAD_QUIP)
     BUILD_COMMAND env QUIP_ARCH=lammps make libquip
     INSTALL_COMMAND ""
     BUILD_IN_SOURCE YES
-    BUILD_BYPRODUCTS <SOURCE_DIR>/build/lammps/libquip.a
+    BUILD_BYPRODUCTS <SOURCE_DIR>/build/lammps/${CMAKE_STATIC_LIBRARY_PREFIX}quip${CMAKE_STATIC_LIBRARY_SUFFIX}
   )
   ExternalProject_get_property(quip_build SOURCE_DIR)
   add_library(LAMMPS::QUIP UNKNOWN IMPORTED)
   set_target_properties(LAMMPS::QUIP PROPERTIES
-    IMPORTED_LOCATION "${SOURCE_DIR}/build/lammps/libquip.a"
+    IMPORTED_LOCATION "${SOURCE_DIR}/build/lammps/${CMAKE_STATIC_LIBRARY_PREFIX}quip${CMAKE_STATIC_LIBRARY_SUFFIX}"
     INTERFACE_LINK_LIBRARIES "${LAPACK_LIBRARIES}")
   target_link_libraries(lammps PRIVATE LAMMPS::QUIP)
   add_dependencies(LAMMPS::QUIP quip_build)

cmake/Modules/Packages/PLUMED.cmake

@@ -47,15 +47,15 @@ if(DOWNLOAD_PLUMED)
   endif()
   message(STATUS "PLUMED download requested - we will build our own")
   if(PLUMED_MODE STREQUAL "STATIC")
-    set(PLUMED_BUILD_BYPRODUCTS "<INSTALL_DIR>/lib/libplumed.a")
+    set(PLUMED_BUILD_BYPRODUCTS "<INSTALL_DIR>/lib/${CMAKE_STATIC_LIBRARY_PREFIX}plumed${CMAKE_STATIC_LIBRARY_SUFFIX}")
   elseif(PLUMED_MODE STREQUAL "SHARED")
-    set(PLUMED_BUILD_BYPRODUCTS "<INSTALL_DIR>/lib/libplumed${CMAKE_SHARED_LIBRARY_SUFFIX};<INSTALL_DIR>/lib/libplumedKernel${CMAKE_SHARED_LIBRARY_SUFFIX}")
+    set(PLUMED_BUILD_BYPRODUCTS "<INSTALL_DIR>/lib/${CMAKE_SHARED_LIBRARY_PREFIX}plumed${CMAKE_SHARED_LIBRARY_SUFFIX};<INSTALL_DIR>/lib/${CMAKE_SHARED_LIBRARY_PREFIX}plumedKernel${CMAKE_SHARED_LIBRARY_SUFFIX}")
   elseif(PLUMED_MODE STREQUAL "RUNTIME")
-    set(PLUMED_BUILD_BYPRODUCTS "<INSTALL_DIR>/lib/libplumedWrapper.a")
+    set(PLUMED_BUILD_BYPRODUCTS "<INSTALL_DIR>/lib/${CMAKE_STATIC_LIBRARY_PREFIX}plumedWrapper${CMAKE_STATIC_LIBRARY_PREFIX}")
   endif()
 
-  set(PLUMED_URL "https://github.com/plumed/plumed2/releases/download/v2.7.4/plumed-src-2.7.4.tgz" CACHE STRING "URL for PLUMED tarball")
+  set(PLUMED_URL "https://github.com/plumed/plumed2/releases/download/v2.8.1/plumed-src-2.8.1.tgz" CACHE STRING "URL for PLUMED tarball")
-  set(PLUMED_MD5 "858e0b6aed173748fc85b6bc8a9dcb3e" CACHE STRING "MD5 checksum of PLUMED tarball")
+  set(PLUMED_MD5 "6bfe72ebdae63dc38a9ca27d9b0e08f8" CACHE STRING "MD5 checksum of PLUMED tarball")
 
   mark_as_advanced(PLUMED_URL)
   mark_as_advanced(PLUMED_MD5)
@@ -78,12 +78,12 @@ if(DOWNLOAD_PLUMED)
   add_library(LAMMPS::PLUMED UNKNOWN IMPORTED)
   add_dependencies(LAMMPS::PLUMED plumed_build)
   if(PLUMED_MODE STREQUAL "STATIC")
-    set_target_properties(LAMMPS::PLUMED PROPERTIES IMPORTED_LOCATION ${INSTALL_DIR}/lib/libplumed.a INTERFACE_LINK_LIBRARIES "${PLUMED_LINK_LIBS};${CMAKE_DL_LIBS}")
+    set_target_properties(LAMMPS::PLUMED PROPERTIES IMPORTED_LOCATION ${INSTALL_DIR}/lib/${CMAKE_STATIC_LIBRARY_PREFIX}plumed${CMAKE_STATIC_LIBRARY_SUFFIX} INTERFACE_LINK_LIBRARIES "${PLUMED_LINK_LIBS};${CMAKE_DL_LIBS}")
   elseif(PLUMED_MODE STREQUAL "SHARED")
-    set_target_properties(LAMMPS::PLUMED PROPERTIES IMPORTED_LOCATION ${INSTALL_DIR}/lib/libplumed${CMAKE_SHARED_LIBRARY_SUFFIX} INTERFACE_LINK_LIBRARIES "${INSTALL_DIR}/lib/libplumedKernel${CMAKE_SHARED_LIBRARY_SUFFIX};${CMAKE_DL_LIBS}")
+    set_target_properties(LAMMPS::PLUMED PROPERTIES IMPORTED_LOCATION ${INSTALL_DIR}/lib/${CMAKE_SHARED_LIBRARY_PREFIX}plumed${CMAKE_SHARED_LIBRARY_SUFFIX} INTERFACE_LINK_LIBRARIES "${INSTALL_DIR}/lib/${CMAKE_SHARED_LIBRARY_PREFIX}plumedKernel${CMAKE_SHARED_LIBRARY_SUFFIX};${CMAKE_DL_LIBS}")
   elseif(PLUMED_MODE STREQUAL "RUNTIME")
-    set_target_properties(LAMMPS::PLUMED PROPERTIES INTERFACE_COMPILE_DEFINITIONS "__PLUMED_DEFAULT_KERNEL=${INSTALL_DIR}/lib/libplumedKernel${CMAKE_SHARED_LIBRARY_SUFFIX}")
+    set_target_properties(LAMMPS::PLUMED PROPERTIES INTERFACE_COMPILE_DEFINITIONS "__PLUMED_DEFAULT_KERNEL=${INSTALL_DIR}/lib/${CMAKE_SHARED_LIBRARY_PREFIX}plumedKernel${CMAKE_SHARED_LIBRARY_SUFFIX}")
-    set_target_properties(LAMMPS::PLUMED PROPERTIES IMPORTED_LOCATION ${INSTALL_DIR}/lib/libplumedWrapper.a INTERFACE_LINK_LIBRARIES "${CMAKE_DL_LIBS}")
+    set_target_properties(LAMMPS::PLUMED PROPERTIES IMPORTED_LOCATION ${INSTALL_DIR}/lib/${CMAKE_STATIC_LIBRARY_PREFIX}plumedWrapper${CMAKE_STATIC_LIBRARY_SUFFIX} INTERFACE_LINK_LIBRARIES "${CMAKE_DL_LIBS}")
   endif()
   set_target_properties(LAMMPS::PLUMED PROPERTIES INTERFACE_INCLUDE_DIRECTORIES ${INSTALL_DIR}/include)
   file(MAKE_DIRECTORY ${INSTALL_DIR}/include)
@@ -96,7 +96,7 @@ else()
   elseif(PLUMED_MODE STREQUAL "SHARED")
     include(${PLUMED_LIBDIR}/plumed/src/lib/Plumed.cmake.shared)
   elseif(PLUMED_MODE STREQUAL "RUNTIME")
-    set_target_properties(LAMMPS::PLUMED PROPERTIES INTERFACE_COMPILE_DEFINITIONS "__PLUMED_DEFAULT_KERNEL=${PLUMED_LIBDIR}/libplumedKernel${CMAKE_SHARED_LIBRARY_SUFFIX}")
+    set_target_properties(LAMMPS::PLUMED PROPERTIES INTERFACE_COMPILE_DEFINITIONS "__PLUMED_DEFAULT_KERNEL=${PLUMED_LIBDIR}/${CMAKE_SHARED_LIBRARY_PREFIX}plumedKernel${CMAKE_SHARED_LIBRARY_SUFFIX}")
     include(${PLUMED_LIBDIR}/plumed/src/lib/Plumed.cmake.runtime)
   endif()
   set_target_properties(LAMMPS::PLUMED PROPERTIES INTERFACE_LINK_LIBRARIES "${PLUMED_LOAD}")

cmake/Modules/Packages/VTK.cmake

@@ -1,4 +1,9 @@
 find_package(VTK REQUIRED NO_MODULE)
-include(${VTK_USE_FILE})
 target_compile_definitions(lammps PRIVATE -DLAMMPS_VTK)
-target_link_libraries(lammps PRIVATE ${VTK_LIBRARIES})
+if (VTK_MAJOR_VERSION VERSION_LESS 9.0)
+  include(${VTK_USE_FILE})
+  target_link_libraries(lammps PRIVATE ${VTK_LIBRARIES})
+else()
+  target_link_libraries(lammps PRIVATE VTK::CommonCore VTK::IOCore VTK::CommonDataModel VTK::IOXML VTK::IOLegacy VTK::IOParallelXML)
+  vtk_module_autoinit(TARGETS lammps MODULES VTK::CommonCore VTK::IOCore VTK::CommonDataModel VTK::IOXML VTK::IOLegacy VTK::IOParallelXML)
+endif()

cmake/presets/all_off.cmake

@@ -56,6 +56,7 @@ set(ALL_PACKAGES
   ML-HDNNP
   ML-IAP
   ML-PACE
+  ML-POD
   ML-QUIP
   ML-RANN
   ML-SNAP

cmake/presets/all_on.cmake

@@ -58,6 +58,7 @@ set(ALL_PACKAGES
   ML-HDNNP
   ML-IAP
   ML-PACE
+  ML-POD
   ML-QUIP
   ML-RANN
   ML-SNAP

cmake/presets/clang.cmake

@@ -28,10 +28,3 @@ set(MPI_CXX "clang++" CACHE STRING "" FORCE)
 set(MPI_CXX_COMPILER "mpicxx" CACHE STRING "" FORCE)
 
 unset(HAVE_OMP_H_INCLUDE CACHE)
-set(OpenMP_C "clang" CACHE STRING "" FORCE)
-set(OpenMP_C_FLAGS "-fopenmp" CACHE STRING "" FORCE)
-set(OpenMP_C_LIB_NAMES "omp" CACHE STRING "" FORCE)
-set(OpenMP_CXX "clang++" CACHE STRING "" FORCE)
-set(OpenMP_CXX_FLAGS "-fopenmp" CACHE STRING "" FORCE)
-set(OpenMP_CXX_LIB_NAMES "omp" CACHE STRING "" FORCE)
-set(OpenMP_omp_LIBRARY "libomp.so" CACHE PATH "" FORCE)

cmake/presets/gcc.cmake

@@ -19,11 +19,3 @@ set(CMAKE_Fortran_FLAGS_DEBUG "-Wall -Og -g -std=f2003" CACHE STRING "" FORCE)
 set(CMAKE_Fortran_FLAGS_RELWITHDEBINFO "-g -O2 -DNDEBUG -std=f2003" CACHE STRING "" FORCE)
 set(CMAKE_Fortran_FLAGS_RELEASE "-O3 -DNDEBUG -std=f2003" CACHE STRING "" FORCE)
 unset(HAVE_OMP_H_INCLUDE CACHE)
-
-set(OpenMP_C "gcc" CACHE STRING "" FORCE)
-set(OpenMP_C_FLAGS "-fopenmp" CACHE STRING "" FORCE)
-set(OpenMP_C_LIB_NAMES "gomp" CACHE STRING "" FORCE)
-set(OpenMP_CXX "g++" CACHE STRING "" FORCE)
-set(OpenMP_CXX_FLAGS "-fopenmp" CACHE STRING "" FORCE)
-set(OpenMP_CXX_LIB_NAMES "gomp" CACHE STRING "" FORCE)
-set(OpenMP_omp_LIBRARY "libgomp.so" CACHE PATH "" FORCE)

cmake/presets/mingw-cross.cmake

@@ -47,6 +47,7 @@ set(WIN_PACKAGES
   MISC
   ML-HDNNP
   ML-IAP
+  ML-POD
   ML-RANN
   ML-SNAP
   MOFFF

cmake/presets/most.cmake

@@ -41,6 +41,7 @@ set(ALL_PACKAGES
   MEAM
   MISC
   ML-IAP
+  ML-POD
   ML-SNAP
   MOFFF
   MOLECULE

cmake/presets/nvhpc.cmake

@@ -0,0 +1,9 @@
+# preset that will enable Nvidia HPC SDK compilers with support for MPI and OpenMP (on Linux boxes)
+
+set(CMAKE_CXX_COMPILER "nvc++" CACHE STRING "" FORCE)
+set(CMAKE_C_COMPILER "nvc" CACHE STRING "" FORCE)
+set(CMAKE_Fortran_COMPILER "nvfortran" CACHE STRING "" FORCE)
+set(MPI_CXX "nvc++" CACHE STRING "" FORCE)
+set(MPI_CXX_COMPILER "mpicxx" CACHE STRING "" FORCE)
+unset(HAVE_OMP_H_INCLUDE CACHE)
+

cmake/presets/pedantic.cmake

@@ -1,4 +1,4 @@
-# preset that will restore gcc/g++ with support for MPI and OpenMP (on Linux boxes)
+# preset that will set gcc/g++ with extra warnings enabled and support for MPI and OpenMP (on Linux boxes)
 
 set(CMAKE_CXX_COMPILER "g++" CACHE STRING "" FORCE)
 set(CMAKE_C_COMPILER "gcc" CACHE STRING "" FORCE)
@@ -17,10 +17,3 @@ set(MPI_Fortran "gfortran" CACHE STRING "" FORCE)
 set(MPI_Fortran_COMPILER "mpifort" CACHE STRING "" FORCE)
 unset(HAVE_OMP_H_INCLUDE CACHE)
 
-set(OpenMP_C "gcc" CACHE STRING "" FORCE)
-set(OpenMP_C_FLAGS "-fopenmp" CACHE STRING "" FORCE)
-set(OpenMP_C_LIB_NAMES "gomp" CACHE STRING "" FORCE)
-set(OpenMP_CXX "g++" CACHE STRING "" FORCE)
-set(OpenMP_CXX_FLAGS "-fopenmp" CACHE STRING "" FORCE)
-set(OpenMP_CXX_LIB_NAMES "gomp" CACHE STRING "" FORCE)
-set(OpenMP_omp_LIBRARY "libgomp.so" CACHE PATH "" FORCE)

cmake/presets/pgi.cmake

@@ -7,10 +7,3 @@ set(MPI_CXX "pgc++" CACHE STRING "" FORCE)
 set(MPI_CXX_COMPILER "mpicxx" CACHE STRING "" FORCE)
 unset(HAVE_OMP_H_INCLUDE CACHE)
 
-set(OpenMP_C "pgcc" CACHE STRING "" FORCE)
-set(OpenMP_C_FLAGS "-mp" CACHE STRING "" FORCE)
-set(OpenMP_C_LIB_NAMES "omp" CACHE STRING "" FORCE)
-set(OpenMP_CXX "pgc++" CACHE STRING "" FORCE)
-set(OpenMP_CXX_FLAGS "-mp" CACHE STRING "" FORCE)
-set(OpenMP_CXX_LIB_NAMES "omp" CACHE STRING "" FORCE)
-set(OpenMP_omp_LIBRARY "libomp.so" CACHE PATH "" FORCE)

doc/Makefile

@@ -38,16 +38,14 @@ endif
 # override settings for PIP commands
 # PIP_OPTIONS = --cert /etc/pki/ca-trust/extracted/openssl/ca-bundle.trust.crt --proxy http://proxy.mydomain.org
 
-#SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())') $(shell test -f $(BUILDDIR)/doxygen/xml/run.stamp && printf -- "-E")
-
 # temporarily disable caching so that the hack for the sphinx-tabs extensions to get proper non-html output works
-SPHINXEXTRA = -E -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())')
+SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())')
 
 # grab list of sources from doxygen config file.
 # we only want to use explicitly listed files.
 DOXYFILES      = $(shell sed -n -e 's/\#.*$$//' -e '/^ *INPUT \+=/,/^[A-Z_]\+ \+=/p' doxygen/Doxyfile.in | sed -e 's/@LAMMPS_SOURCE_DIR@/..\/src/g' -e 's/\\//g' -e 's/ \+/ /' -e 's/[A-Z_]\+ \+= *\(YES\|NO\|\)//') 
 
-.PHONY: help clean-all clean clean-spelling epub mobi rst html pdf spelling anchor_check style_check char_check xmlgen fasthtml
+.PHONY: help clean-all clean clean-spelling epub mobi html pdf spelling anchor_check style_check char_check role_check xmlgen fasthtml
 
 # ------------------------------------------
 
@@ -89,6 +87,8 @@ html: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX)
 	@$(MAKE) $(MFLAGS) -C graphviz all
 	@(\
 		. $(VENV)/bin/activate ; env PYTHONWARNINGS= \
+		sphinx-build -E $(SPHINXEXTRA) -b html -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) html ;\
+		touch $(RSTDIR)/Fortran.rst ;\
 		sphinx-build $(SPHINXEXTRA) -b html -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) html ;\
 		ln -sf Manual.html html/index.html;\
 		rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\
@@ -96,6 +96,7 @@ html: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX)
 		rst_anchor_check src/*.rst ;\
 		python $(BUILDDIR)/utils/check-packages.py -s ../src -d src ;\
 		env LC_ALL=C grep -n '[^ -~]' $(RSTDIR)/*.rst ;\
+		env LC_ALL=C grep -n ' :[a-z]\+`' $(RSTDIR)/*.rst ;\
 		python $(BUILDDIR)/utils/check-styles.py -s ../src -d src ;\
 		echo "############################################" ;\
 		deactivate ;\
@@ -114,7 +115,9 @@ fasthtml: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX)
 	@mkdir -p fasthtml
 	@(\
 		. $(VENV)/bin/activate ; env PYTHONWARNINGS= \
-		sphinx-build -j 4 -b html -c $(SPHINXCONFIG) -d $(BUILDDIR)/fasthtml/doctrees $(RSTDIR) fasthtml ;\
+		sphinx-build $(SPHINXEXTRA) -b html -c $(SPHINXCONFIG) -d $(BUILDDIR)/fasthtml/doctrees $(RSTDIR) fasthtml ;\
+		touch $(RSTDIR)/Fortran.rst ;\
+		sphinx-build $(SPHINXEXTRA) -b html -c $(SPHINXCONFIG) -d $(BUILDDIR)/fasthtml/doctrees $(RSTDIR) fasthtml ;\
 		deactivate ;\
 	)
 	@rm -rf fasthtml/_sources
@@ -144,6 +147,8 @@ epub: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK)
 	@cp src/JPG/*.* epub/JPG
 	@(\
 		. $(VENV)/bin/activate ;\
+		sphinx-build -E $(SPHINXEXTRA) -b epub -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) epub ;\
+		touch $(RSTDIR)/Fortran.rst ;\
 		sphinx-build $(SPHINXEXTRA) -b epub -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) epub ;\
 		rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\
 		deactivate ;\
@@ -163,12 +168,15 @@ pdf: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK)
 	@if [ "$(HAS_PDFLATEX)" == "NO" ] ; then echo "PDFLaTeX or latexmk were not found! Please check README for further instructions" 1>&2; exit 1; fi
 	@(\
 		. $(VENV)/bin/activate ; env PYTHONWARNINGS= \
-		sphinx-build $(SPHINXEXTRA) -b latex -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) latex ;\
+		sphinx-build -E $(SPHINXEXTRA) -b latex -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) latex ;\
+		touch $(RSTDIR)/Fortran.rst ;\
+		sphinx-build  $(SPHINXEXTRA) -b latex -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) latex ;\
 		rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\
 		echo "############################################" ;\
 		rst_anchor_check src/*.rst ;\
 		python utils/check-packages.py -s ../src -d src ;\
 		env LC_ALL=C grep -n '[^ -~]' $(RSTDIR)/*.rst ;\
+		env LC_ALL=C grep -n ' :[a-z]\+`' $(RSTDIR)/*.rst ;\
 		python utils/check-styles.py -s ../src -d src ;\
 		echo "############################################" ;\
 		deactivate ;\
@@ -214,6 +222,9 @@ package_check : $(VENV)
 char_check :
 	@( env LC_ALL=C grep -n '[^ -~]' $(RSTDIR)/*.rst && exit 1 || : )
 
+role_check :
+	@( env LC_ALL=C grep -n ' :[a-z]\+`' $(RSTDIR)/*.rst && exit 1 || : )
+
 xmlgen : doxygen/xml/index.xml
 
 doxygen/Doxyfile: doxygen/Doxyfile.in

doc/lammps.1

@@ -1,7 +1,7 @@
-.TH LAMMPS "1" "15 September 2022" "2022-9-15"
+.TH LAMMPS "1" "22 December 2022" "2022-12-22"
 .SH NAME
 .B LAMMPS
-\- Molecular Dynamics Simulator.  Version 15 September 2022
+\- Molecular Dynamics Simulator.  Version 22 December 2022
 
 .SH SYNOPSIS
 .B lmp

doc/src/Build_development.rst

@@ -147,6 +147,16 @@ compile and will download and compile a specific recent version of the
 `Googletest <https://github.com/google/googletest/>`_ C++ test framework
 for implementing the tests.
 
+.. admonition:: Software version requirements for testing
+   :class: note
+
+   The compiler and library version requirements for the testing
+   framework are more strict than for the main part of LAMMPS.  For
+   example the default GNU C++ and Fortran compilers of RHEL/CentOS 7.x
+   (version 4.8.x) are not sufficient.  The CMake configuration will try
+   to detect compatible versions and either skip incompatible tests or
+   stop with an error.
+
 After compilation is complete, the unit testing is started in the build
 folder using the ``ctest`` command, which is part of the CMake software.
 The output of this command will be looking something like this::

doc/src/Build_extras.rst

@@ -36,6 +36,7 @@ This is the list of packages that may require additional steps.
    * :ref:`AWPMD <awpmd>`
    * :ref:`COLVARS <colvars>`
    * :ref:`COMPRESS <compress>`
+   * :ref:`ELECTRODE <electrode>`
    * :ref:`GPU <gpu>`
    * :ref:`H5MD <h5md>`
    * :ref:`INTEL <intel>`
@@ -48,6 +49,7 @@ This is the list of packages that may require additional steps.
    * :ref:`ML-HDNNP <ml-hdnnp>`
    * :ref:`ML-IAP <mliap>`
    * :ref:`ML-PACE <ml-pace>`
+   * :ref:`ML-POD <ml-pod>`
    * :ref:`ML-QUIP <ml-quip>`
    * :ref:`MOLFILE <molfile>`
    * :ref:`MSCG <mscg>`
@@ -234,7 +236,7 @@ LAMMPS code.  This also applies to the ``-DLAMMPS_BIGBIG``\ ,
 Makefile you use.
 
 You can also build the library in one step from the ``lammps/src`` dir,
-using a command like these, which simply invoke the ``lib/gpu/Install.py``
+using a command like these, which simply invokes the ``lib/gpu/Install.py``
 script with the specified args:
 
 .. code-block:: bash
@@ -350,7 +352,7 @@ minutes to hours) to build.  Of course you only need to do that once.)
       You can download and build the KIM library manually if you prefer;
       follow the instructions in ``lib/kim/README``.  You can also do
       this in one step from the lammps/src directory, using a command like
-      these, which simply invoke the ``lib/kim/Install.py`` script with
+      these, which simply invokes the ``lib/kim/Install.py`` script with
       the specified args.
 
       .. code-block:: bash
@@ -954,7 +956,7 @@ more details.
       You can download and build the MS-CG library manually if you
       prefer; follow the instructions in ``lib/mscg/README``\ .  You can
       also do it in one step from the ``lammps/src`` dir, using a
-      command like these, which simply invoke the
+      command like these, which simply invokes the
       ``lib/mscg/Install.py`` script with the specified args:
 
       .. code-block:: bash
@@ -1011,7 +1013,7 @@ POEMS package
       ``lib/poems``\ .  You can do this manually if you prefer; follow
       the instructions in ``lib/poems/README``\ .  You can also do it in
       one step from the ``lammps/src`` dir, using a command like these,
-      which simply invoke the ``lib/poems/Install.py`` script with the
+      which simply invokes the ``lib/poems/Install.py`` script with the
       specified args:
 
       .. code-block:: bash
@@ -1100,7 +1102,7 @@ binary package provided by your operating system.
       You can download and build the Voro++ library manually if you
       prefer; follow the instructions in ``lib/voronoi/README``.  You
       can also do it in one step from the ``lammps/src`` dir, using a
-      command like these, which simply invoke the
+      command like these, which simply invokes the
       ``lib/voronoi/Install.py`` script with the specified args:
 
       .. code-block:: bash
@@ -1179,7 +1181,7 @@ The ATC package requires the MANYBODY package also be installed.
       ``lib/atc``.  You can do this manually if you prefer; follow the
       instructions in ``lib/atc/README``.  You can also do it in one
       step from the ``lammps/src`` dir, using a command like these,
-      which simply invoke the ``lib/atc/Install.py`` script with the
+      which simply invokes the ``lib/atc/Install.py`` script with the
       specified args:
 
       .. code-block:: bash
@@ -1230,7 +1232,7 @@ AWPMD package
       ``lib/awpmd``.  You can do this manually if you prefer; follow the
       instructions in ``lib/awpmd/README``.  You can also do it in one
       step from the ``lammps/src`` dir, using a command like these,
-      which simply invoke the ``lib/awpmd/Install.py`` script with the
+      which simply invokes the ``lib/awpmd/Install.py`` script with the
       specified args:
 
       .. code-block:: bash
@@ -1293,7 +1295,7 @@ be built for the most part with all major versions of the C++ language.
 
       In general, it is safer to use build setting consistent with the
       rest of LAMMPS.  This is best carried out from the LAMMPS src
-      directory using a command like these, which simply invoke the
+      directory using a command like these, which simply invokes the
       ``lib/colvars/Install.py`` script with the specified args:
 
       .. code-block:: bash
@@ -1334,20 +1336,30 @@ This package depends on the KSPACE package.
 
    .. tab:: CMake build
 
-      No additional settings are needed besides ``-D PKG_KSPACE=yes`` and ``-D
+      No additional settings are needed besides ``-D PKG_KSPACE=yes`` and
-      PKG_ELECTRODE=yes``.
+      ``-D PKG_ELECTRODE=yes``.
 
    .. tab:: Traditional make
 
-      The package is activated with ``make yes-KSPACE`` and ``make
+      Before building LAMMPS, you must configure the ELECTRODE support
-      yes-ELECTRODE``
+      libraries and settings in ``lib/electrode``.  You can do this
+      manually, if you prefer, or do it in one step from the
+      ``lammps/src`` dir, using a command like these, which simply
+      invokes the ``lib/electrode/Install.py`` script with the specified
+      args:
+
+      .. code-block:: bash
+
+         $ make lib-electrode                   # print help message
+         $ make lib-electrode args="-m serial"  # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
+         $ make lib-electrode args="-m mpi"     # build with default MPI compiler (settings as with "make mpi")
 
 
-      Note that the ``Makefile.lammps`` file has settings for the BLAS and
+      Note that the ``Makefile.lammps`` file has settings for the BLAS
-      LAPACK linear algebra libraries.  As explained in ``lib/awpmd/README``
+      and LAPACK linear algebra libraries.  These can either exist on
-      these can either exist on your system, or you can use the files provided
+      your system, or you can use the files provided in ``lib/linalg``.
-      in ``lib/linalg``.  In the latter case you also need to build the library
+      In the latter case you also need to build the library in
-      in ``lib/linalg`` with a command like these:
+      ``lib/linalg`` with a command like these:
 
       .. code-block:: bash
 
@@ -1356,6 +1368,9 @@ This package depends on the KSPACE package.
          $ make lib-linalg args="-m mpi"       # build with default MPI Fortran compiler (settings as with "make mpi")
          $ make lib-linalg args="-m gfortran"  # build with GNU Fortran compiler
 
+      The package itself is activated with ``make yes-KSPACE`` and
+      ``make yes-ELECTRODE``
+
 ----------
 
 .. _ml-pace:
@@ -1398,6 +1413,49 @@ at: `https://github.com/ICAMS/lammps-user-pace/ <https://github.com/ICAMS/lammps
 
 ----------
 
+.. _ml-pod:
+
+ML-POD package
+-----------------------------
+
+.. tabs::
+
+   .. tab:: CMake build
+
+      No additional settings are needed besides ``-D PKG_ML-POD=yes``.
+
+   .. tab:: Traditional make
+
+      Before building LAMMPS, you must configure the ML-POD support
+      settings in ``lib/mlpod``.  You can do this manually, if you
+      prefer, or do it in one step from the ``lammps/src`` dir, using a
+      command like the following, which simply invoke the
+      ``lib/mlpod/Install.py`` script with the specified args:
+
+      .. code-block:: bash
+
+         $ make lib-mlpod                   # print help message
+         $ make lib-mlpod args="-m serial"  # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
+         $ make lib-mlpod args="-m mpi"     # build with default MPI compiler (settings as with "make mpi")
+         $ make lib-mlpod args="-m mpi -e linalg"   # same as above but use the bundled linalg lib
+
+      Note that the ``Makefile.lammps`` file has settings to use the BLAS
+      and LAPACK linear algebra libraries.  These can either exist on
+      your system, or you can use the files provided in ``lib/linalg``.
+      In the latter case you also need to build the library in
+      ``lib/linalg`` with a command like these:
+
+      .. code-block:: bash
+
+         $ make lib-linalg                     # print help message
+         $ make lib-linalg args="-m serial"    # build with GNU Fortran compiler (settings as with "make serial")
+         $ make lib-linalg args="-m mpi"       # build with default MPI Fortran compiler (settings as with "make mpi")
+         $ make lib-linalg args="-m gfortran"  # build with GNU Fortran compiler
+
+      The package itself is activated with ``make yes-ML-POD``.
+
+----------
+
 .. _plumed:
 
 PLUMED package
@@ -1555,7 +1613,7 @@ the HDF5 library.
       ``lib/h5md``.  You can do this manually if you prefer; follow the
       instructions in ``lib/h5md/README``.  You can also do it in one
       step from the ``lammps/src`` dir, using a command like these,
-      which simply invoke the ``lib/h5md/Install.py`` script with the
+      which simply invokes the ``lib/h5md/Install.py`` script with the
       specified args:
 
       .. code-block:: bash
@@ -1611,7 +1669,7 @@ details please see ``lib/hdnnp/README`` and the `n2p2 build documentation
       You can download and build the *n2p2* library manually if you prefer;
       follow the instructions in ``lib/hdnnp/README``\ . You can also do it in
       one step from the ``lammps/src`` dir, using a command like these, which
-      simply invoke the ``lib/hdnnp/Install.py`` script with the specified args:
+      simply invokes the ``lib/hdnnp/Install.py`` script with the specified args:
 
       .. code-block:: bash
 
@@ -1748,7 +1806,7 @@ they will be downloaded the first time this package is installed.
       Before building LAMMPS, you must build the *mesont* library in
       ``lib/mesont``\ .  You can also do it in one step from the
       ``lammps/src`` dir, using a command like these, which simply
-      invoke the ``lib/mesont/Install.py`` script with the specified
+      invokes the ``lib/mesont/Install.py`` script with the specified
       args:
 
       .. code-block:: bash
@@ -1917,7 +1975,7 @@ verified to work in February 2020 with Quantum Espresso versions 6.3 to
       ``lib/qmmm``.  You can do this manually if you prefer; follow the
       first two steps explained in ``lib/qmmm/README``.  You can also do
       it in one step from the ``lammps/src`` dir, using a command like
-      these, which simply invoke the ``lib/qmmm/Install.py`` script with
+      these, which simply invokes the ``lib/qmmm/Install.py`` script with
       the specified args:
 
       .. code-block:: bash
@@ -2025,7 +2083,7 @@ To build with this package, you must download and build the
       You can download and build the ScaFaCoS library manually if you
       prefer; follow the instructions in ``lib/scafacos/README``.  You
       can also do it in one step from the ``lammps/src`` dir, using a
-      command like these, which simply invoke the
+      command like these, which simply invokes the
       ``lib/scafacos/Install.py`` script with the specified args:
 
       .. code-block:: bash
@@ -2069,7 +2127,7 @@ Eigen3 is a template library, so you do not need to build it.
       You can download the Eigen3 library manually if you prefer; follow
       the instructions in ``lib/smd/README``.  You can also do it in one
       step from the ``lammps/src`` dir, using a command like these,
-      which simply invoke the ``lib/smd/Install.py`` script with the
+      which simply invokes the ``lib/smd/Install.py`` script with the
       specified args:
 
       .. code-block:: bash

doc/src/Commands_all.rst

@@ -31,7 +31,6 @@ table above.
    * :doc:`bond_style <bond_style>`
    * :doc:`bond_write <bond_write>`
    * :doc:`boundary <boundary>`
-   * :doc:`box <box>`
    * :doc:`change_box <change_box>`
    * :doc:`clear <clear>`
    * :doc:`comm_modify <comm_modify>`
@@ -90,8 +89,7 @@ table above.
    * :doc:`region <region>`
    * :doc:`replicate <replicate>`
    * :doc:`rerun <rerun>`
-   * :doc:`reset_atom_ids <reset_atom_ids>`
+   * :doc:`reset_atoms <reset_atoms>`
-   * :doc:`reset_mol_ids <reset_mol_ids>`
    * :doc:`reset_timestep <reset_timestep>`
    * :doc:`restart <restart>`
    * :doc:`run <run>`
@@ -127,6 +125,7 @@ additional letter in parenthesis: k = KOKKOS.
    * :doc:`group2ndx <group2ndx>`
    * :doc:`hyper <hyper>`
    * :doc:`kim <kim_commands>`
+   * :doc:`fitpod <fitpod_command>`
    * :doc:`mdi <mdi>`
    * :doc:`ndx2group <group2ndx>`
    * :doc:`neb <neb>`

doc/src/Commands_category.rst

@@ -25,7 +25,6 @@ Setup simulation box:
    :columns: 4
 
    * :doc:`boundary <boundary>`
-   * :doc:`box <box>`
    * :doc:`change_box <change_box>`
    * :doc:`create_box <create_box>`
    * :doc:`dimension <dimension>`

doc/src/Commands_compute.rst

@@ -107,6 +107,7 @@ KOKKOS, o = OPENMP, t = OPT.
    * :doc:`pressure/uef <compute_pressure_uef>`
    * :doc:`property/atom <compute_property_atom>`
    * :doc:`property/chunk <compute_property_chunk>`
+   * :doc:`property/grid <compute_property_grid>`
    * :doc:`property/local <compute_property_local>`
    * :doc:`ptm/atom <compute_ptm_atom>`
    * :doc:`rdf <compute_rdf>`

doc/src/Commands_dump.rst

@@ -36,7 +36,8 @@ An alphabetic list of all LAMMPS :doc:`dump <dump>` commands.
    * :doc:`custom/mpiio <dump>`
    * :doc:`custom/zstd <dump>`
    * :doc:`dcd <dump>`
-   * :doc:`deprecated <dump>`
+   * :doc:`grid <dump>`
+   * :doc:`grid/vtk <dump>`
    * :doc:`h5md <dump_h5md>`
    * :doc:`image <dump_image>`
    * :doc:`local <dump>`

doc/src/Commands_fix.rst

@@ -38,6 +38,7 @@ OPT.
    * :doc:`ave/chunk <fix_ave_chunk>`
    * :doc:`ave/correlate <fix_ave_correlate>`
    * :doc:`ave/correlate/long <fix_ave_correlate_long>`
+   * :doc:`ave/grid <fix_ave_grid>`
    * :doc:`ave/histo <fix_ave_histo>`
    * :doc:`ave/histo/weight <fix_ave_histo>`
    * :doc:`ave/time <fix_ave_time>`
@@ -65,13 +66,13 @@ OPT.
    * :doc:`drude <fix_drude>`
    * :doc:`drude/transform/direct <fix_drude_transform>`
    * :doc:`drude/transform/inverse <fix_drude_transform>`
-   * :doc:`dt/reset <fix_dt_reset>`
+   * :doc:`dt/reset (k) <fix_dt_reset>`
    * :doc:`edpd/source <fix_dpd_source>`
    * :doc:`efield <fix_efield>`
    * :doc:`ehex <fix_ehex>`
-   * :doc:`electrode/conp (i) <fix_electrode_conp>`
+   * :doc:`electrode/conp (i) <fix_electrode>`
-   * :doc:`electrode/conq (i) <fix_electrode_conp>`
+   * :doc:`electrode/conq (i) <fix_electrode>`
-   * :doc:`electrode/thermo (i) <fix_electrode_conp>`
+   * :doc:`electrode/thermo (i) <fix_electrode>`
    * :doc:`electron/stopping <fix_electron_stopping>`
    * :doc:`electron/stopping/fit <fix_electron_stopping>`
    * :doc:`enforce2d (k) <fix_enforce2d>`
@@ -213,6 +214,7 @@ OPT.
    * :doc:`saed/vtk <fix_saed_vtk>`
    * :doc:`setforce (k) <fix_setforce>`
    * :doc:`setforce/spin <fix_setforce>`
+   * :doc:`sgcmc <fix_sgcmc>`
    * :doc:`shake (k) <fix_shake>`
    * :doc:`shardlow (k) <fix_shardlow>`
    * :doc:`smd <fix_smd>`
@@ -249,7 +251,7 @@ OPT.
    * :doc:`tune/kspace <fix_tune_kspace>`
    * :doc:`vector <fix_vector>`
    * :doc:`viscosity <fix_viscosity>`
-   * :doc:`viscous <fix_viscous>`
+   * :doc:`viscous (k) <fix_viscous>`
    * :doc:`viscous/sphere <fix_viscous_sphere>`
    * :doc:`wall/body/polygon <fix_wall_body_polygon>`
    * :doc:`wall/body/polyhedron <fix_wall_body_polyhedron>`

doc/src/Commands_pair.rst

@@ -93,8 +93,8 @@ OPT.
    * :doc:`coul/wolf/cs <pair_cs>`
    * :doc:`dpd (giko) <pair_dpd>`
    * :doc:`dpd/fdt <pair_dpd_fdt>`
-   * :doc:`dpd/ext (k) <pair_dpd_ext>`
+   * :doc:`dpd/ext (ko) <pair_dpd_ext>`
-   * :doc:`dpd/ext/tstat (k) <pair_dpd_ext>`
+   * :doc:`dpd/ext/tstat (ko) <pair_dpd_ext>`
    * :doc:`dpd/fdt/energy (k) <pair_dpd_fdt>`
    * :doc:`dpd/tstat (gko) <pair_dpd>`
    * :doc:`dsmc <pair_dsmc>`
@@ -205,7 +205,7 @@ OPT.
    * :doc:`mesont/tpm <pair_mesont_tpm>`
    * :doc:`mgpt <pair_mgpt>`
    * :doc:`mie/cut (g) <pair_mie>`
-   * :doc:`mliap <pair_mliap>`
+   * :doc:`mliap (k) <pair_mliap>`
    * :doc:`mm3/switch3/coulgauss/long <pair_lj_switch3_coulgauss_long>`
    * :doc:`momb <pair_momb>`
    * :doc:`morse (gkot) <pair_morse>`
@@ -237,6 +237,7 @@ OPT.
    * :doc:`oxrna2/coaxstk <pair_oxrna2>`
    * :doc:`pace (k) <pair_pace>`
    * :doc:`pace/extrapolation <pair_pace>`
+   * :doc:`pod <pair_pod>`
    * :doc:`peri/eps <pair_peri>`
    * :doc:`peri/lps (o) <pair_peri>`
    * :doc:`peri/pmb (o) <pair_peri>`
@@ -295,6 +296,7 @@ OPT.
    * :doc:`vashishta (gko) <pair_vashishta>`
    * :doc:`vashishta/table (o) <pair_vashishta>`
    * :doc:`wf/cut <pair_wf_cut>`
+   * :doc:`ylz <pair_ylz>`
    * :doc:`yukawa (gko) <pair_yukawa>`
    * :doc:`yukawa/colloid (go) <pair_yukawa_colloid>`
    * :doc:`zbl (gko) <pair_zbl>`

doc/src/Commands_removed.rst

@@ -2,14 +2,17 @@ Removed commands and packages
 =============================
 
 This page lists LAMMPS commands and packages that have been removed from
-the distribution and provides suggestions for alternatives or replacements.
+the distribution and provides suggestions for alternatives or
-LAMMPS has special dummy styles implemented, that will stop LAMMPS and
+replacements.  LAMMPS has special dummy styles implemented, that will
-print a suitable error message in most cases, when a style/command is used
+stop LAMMPS and print a suitable error message in most cases, when a
-that has been removed.
+style/command is used that has been removed or will replace the command
+with the direct alternative (if available) and print a warning.
 
 Fix ave/spatial and fix ave/spatial/sphere
 ------------------------------------------
 
+.. deprecated:: 11Dec2015
+
 The fixes ave/spatial and ave/spatial/sphere have been removed from LAMMPS
 since they were superseded by the more general and extensible "chunk
 infrastructure".  Here the system is partitioned in one of many possible
@@ -17,10 +20,23 @@ ways through the :doc:`compute chunk/atom <compute_chunk_atom>` command
 and then averaging is done using :doc:`fix ave/chunk <fix_ave_chunk>`.
 Please refer to the :doc:`chunk HOWTO <Howto_chunk>` section for an overview.
 
-Reset_ids command
+Box command
------------------
+-----------
 
-The reset_ids command has been renamed to :doc:`reset_atom_ids <reset_atom_ids>`.
+.. deprecated:: 22Dec2022
+
+The *box* command has been removed and the LAMMPS code changed so it won't
+be needed.  If present, LAMMPS will ignore the command and print a warning.
+
+Reset_ids, reset_atom_ids, reset_mol_ids commands
+-------------------------------------------------
+
+.. deprecated:: 22Dec2022
+
+The *reset_ids*, *reset_atom_ids*, and *reset_mol_ids* commands have
+been folded into the :doc:`reset_atoms <reset_atoms>` command.  If
+present, LAMMPS will replace the commands accordingly and print a
+warning.
 
 MEAM package
 ------------
@@ -30,18 +46,21 @@ The code in the :ref:`MEAM package <PKG-MEAM>` is a translation of the
 Fortran code of MEAM into C++, which removes several restrictions
 (e.g. there can be multiple instances in hybrid pair styles) and allows
 for some optimizations leading to better performance.  The pair style
-:doc:`meam <pair_meam>` has the exact same syntax.
+:doc:`meam <pair_meam>` has the exact same syntax.  For a transition
+period the C++ version of MEAM was called USER-MEAMC so it could
+coexist with the Fortran version.
 
 REAX package
 ------------
 
 The REAX package has been removed since it was superseded by the
-:ref:`REAXFF package <PKG-REAXFF>`.  The REAXFF
+:ref:`REAXFF package <PKG-REAXFF>`.  The REAXFF package has been tested
-package has been tested to yield equivalent results to the REAX package,
+to yield equivalent results to the REAX package, offers better
-offers better performance, supports OpenMP multi-threading via OPENMP,
+performance, supports OpenMP multi-threading via OPENMP, and GPU and
-and GPU and threading parallelization through KOKKOS.  The new pair styles
+threading parallelization through KOKKOS.  The new pair styles are not
-are not syntax compatible with the removed reax pair style, so input
+syntax compatible with the removed reax pair style, so input files will
-files will have to be adapted.
+have to be adapted.  The REAXFF package was originally called
+USER-REAXC.
 
 USER-CUDA package
 -----------------
@@ -60,5 +79,6 @@ restart2data tool
 The functionality of the restart2data tool has been folded into the
 LAMMPS executable directly instead of having a separate tool.  A
 combination of the commands :doc:`read_restart <read_restart>` and
-:doc:`write_data <write_data>` can be used to the same effect.  For added
+:doc:`write_data <write_data>` can be used to the same effect.  For
-convenience this conversion can also be triggered by :doc:`command line flags <Run_options>`
+added convenience this conversion can also be triggered by
+:doc:`command line flags <Run_options>`

doc/src/Developer.rst

@@ -23,3 +23,4 @@ of time and requests from the LAMMPS user community.
    Classes
    Developer_platform
    Developer_utils
+   Developer_grid

doc/src/Developer_code_design.rst

@@ -50,7 +50,7 @@ parallel each MPI process creates such an instance.  This can be seen
 in the ``main.cpp`` file where the core steps of running a LAMMPS
 simulation are the following 3 lines of code:
 
-.. code-block:: C++
+.. code-block:: c++
 
     LAMMPS *lammps = new LAMMPS(argc, argv, lammps_comm);
     lammps->input->file();
@@ -78,7 +78,7 @@ LAMMPS makes extensive use of the object oriented programming (OOP)
 principles of *compositing* and *inheritance*. Classes like the
 ``LAMMPS`` class are a **composite** containing pointers to instances
 of other classes like ``Atom``, ``Comm``, ``Force``, ``Neighbor``,
-``Modify``, and so on.  Each of these classes implement certain
+``Modify``, and so on.  Each of these classes implements certain
 functionality by storing and manipulating data related to the
 simulation and providing member functions that trigger certain
 actions.  Some of those classes like ``Force`` are themselves
@@ -87,9 +87,9 @@ interactions.  Similarly the ``Modify`` class contains a list of
 ``Fix`` and ``Compute`` classes.  If the input commands that
 correspond to these classes include the word *style*, then LAMMPS
 stores only a single instance of that class.  E.g. *atom_style*,
-*comm_style*, *pair_style*, *bond_style*.  It the input command does
+*comm_style*, *pair_style*, *bond_style*.  If the input command does
-not include the word *style*, there can be many instances of that
+**not** include the word *style*, then there may be many instances of
-class defined.  E.g. *region*, *fix*, *compute*, *dump*.
+that class defined, for example *region*, *fix*, *compute*, *dump*.
 
 **Inheritance** enables creation of *derived* classes that can share
 common functionality in their base class while providing a consistent
@@ -232,7 +232,7 @@ macro ``PairStyle()`` will associate the style name "lj/cut"
 with a factory function creating an instance of the ``PairLJCut``
 class.
 
-.. code-block:: C++
+.. code-block:: c++
 
    // from force.h
    typedef Pair *(*PairCreator)(LAMMPS *);
@@ -360,7 +360,7 @@ characters; "{:<8}" would do this as left aligned, "{:^8}" as centered,
 argument type must be compatible or else the {fmt} formatting code will
 throw an exception. Some format string examples are given below:
 
-.. code-block:: C
+.. code-block:: c++
 
    auto mesg = fmt::format("  CPU time: {:4d}:{:02d}:{:02d}\n", cpuh, cpum, cpus);
    mesg = fmt::format("{:<8s}| {:<10.5g} | {:<10.5g} | {:<10.5g} |{:6.1f} |{:6.2f}\n",

doc/src/Developer_grid.rst

@@ -0,0 +1,846 @@
+Use of distributed grids within style classes
+---------------------------------------------
+
+.. versionadded:: 22Dec2022
+
+The LAMMPS source code includes two classes which facilitate the
+creation and use of distributed grids.  These are the Grid2d and
+Grid3d classes in the src/grid2d.cpp.h and src/grid3d.cpp.h files
+respectively.  As the names imply, they are used for 2d or 3d
+simulations, as defined by the :doc:`dimension <dimension>` command.
+
+The :doc:`Howto_grid <Howto_grid>` page gives an overview of how
+distributed grids are defined from a user perspective, lists LAMMPS
+commands which use them, and explains how grid cell data is referenced
+from an input script.  Please read that page first as it motivates the
+coding details discussed here.
+
+This doc page is for users who wish to write new styles (input script
+commands) which use distributed grids.  There are a variety of
+material models and analysis methods which use atoms (or
+coarse-grained particles) and grids in tandem.
+
+A *distributed* grid means each processor owns a subset of the grid
+cells.  In LAMMPS, the subset for each processor will be a sub-block
+of grid cells with low and high index bounds in each dimension of the
+grid.  The union of the sub-blocks across all processors is the global
+grid.
+
+More specifically, a grid point is defined for each cell (by default
+the center point), and a processor owns a grid cell if its point is
+within the processor's spatial sub-domain.  The union of processor
+sub-domains is the global simulation box.  If a grid point is on the
+boundary of two sub-domains, the lower processor owns the grid cell.  A
+processor may also store copies of ghost cells which surround its
+owned cells.
+
+----------
+
+Style commands
+^^^^^^^^^^^^^^
+
+Style commands which can define and use distributed grids include the
+:doc:`compute <compute>`, :doc:`fix <fix>`, :doc:`pair <pair_style>`,
+and :doc:`kspace <kspace_style>` styles.  If you wish grid cell data
+to persist across timesteps, then use a fix.  If you wish grid cell
+data to be accessible by other commands, then use a fix or compute.
+Currently in LAMMPS, the :doc:`pair_style amoeba <pair_amoeba>`,
+:doc:`kspace_style pppm <kspace_style>`, and :doc:`kspace_style msm
+<kspace_style>` commands use distributed grids but do not require
+either of these capabilities; they thus create and use distributed
+grids internally.  Note that a pair style which needs grid cell data
+to persist could be coded to work in tandem with a fix style which
+provides that capability.
+
+The *size* of a grid is specified by the number of grid cells in each
+dimension of the simulation domain.  In any dimension the size can be
+any value >= 1.  Thus a 10x10x1 grid for a 3d simulation is
+effectively a 2d grid, where each grid cell spans the entire
+z-dimension.  A 1x100x1 grid for a 3d simulation is effectively a 1d
+grid, where grid cells are a series of thin xz slabs in the
+y-dimension.  It is even possible to define a 1x1x1 3d grid, though it
+may be inefficient to use it in a computational sense.
+
+Note that the choice of grid size is independent of the number of
+processors or their layout in a grid of processor sub-domains which
+overlays the simulations domain.  Depending on the distributed grid
+size, a single processor may own many 1000s or no grid cells.
+
+A command can define multiple grids, each of a different size.  Each
+grid is an instantiation of the Grid2d or Grid3d class.
+
+The command also defines what data it will store for each grid it
+creates and it allocates the multi-dimensional array(s) needed to
+store the data.  No grid cell data is stored within the Grid2d or
+Grid3d classes.
+
+If a single value per grid cell is needed, the data array will have
+the same dimension as the grid, i.e. a 2d array for a 2d grid,
+likewise for 3d.  If multiple values per grid cell are needed, the
+data array will have one more dimension than the grid, i.e. a 3d array
+for a 2d grid, or 4d array for a 3d grid.  A command can choose to
+define multiple data arrays for each grid it defines.
+
+----------
+
+Grid data allocation and access
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The simplest way for a command to allocate and access grid cell data
+is to use the *create_offset()* methods provided by the Memory class.
+Arguments for these methods can be values returned by the
+*setup_grid()* method (described below), which define the extent of
+the grid cells (owned+ghost) the processor owns.  These 4 methods
+allocate memory for 2d (first two) and 3d (second two) grid data.  The
+two methods that end in "_one" allocate an array which stores a single
+value per grid cell.  The two that end in "_multi" allocate an array
+which stores *Nvalues* per grid cell.
+
+.. code-block:: c++
+
+   // single value per cell for a 2d grid = 2d array
+   memory->create2d_offset(data2d_one, nylo_out, nyhi_out,
+                           nxlo_out, nxhi_out, "data2d_one");
+
+   // nvalues per cell for a 2d grid = 3d array
+   memory->create3d_offset_last(data2d_multi, nylo_out, nyhi_out,
+                                nxlo_out, nxhi_out, nvalues, "data2d_multi");
+
+   // single value per cell for a 3d grid = 3d array
+   memory->create3d_offset(data3d_one, nzlo_out, nzhi_out, nylo_out,
+                           nyhi_out, nxlo_out, nxhi_out, "data3d_one");
+
+   // nvalues per cell for a 3d grid = 4d array
+   memory->create4d_offset_last(data3d_multi, nzlo_out, nzhi_out, nylo_out,
+                                nyhi_out, nxlo_out, nxhi_out, nvalues,
+                                "data3d_multi");
+
+Note that these multi-dimensional arrays are allocated as contiguous
+chunks of memory where the x-index of the grid varies fastest, then y,
+and the z-index slowest.  For multiple values per grid cell, the
+Nvalues are contiguous, so their index varies even faster than the
+x-index.
+
+The key point is that the "offset" methods create arrays which are
+indexed by the range of indices which are the bounds of the sub-block
+of the global grid owned by this processor.  This means loops like
+these can be written in the caller code to loop over owned grid cells,
+where the "i" loop bounds are the range of owned grid cells for the
+processor.  These are the bounds returned by the *setup_grid()*
+method:
+
+.. code-block:: c++
+
+    for (int iy = iylo; iy <= iyhi; iy++)
+      for (int ix = ixlo; ix <= ixhi; ix++)
+        data2d_one[iy][ix] = 0.0;
+
+    for (int iy = iylo; iy <= iyhi; iy++)
+      for (int ix = ixlo; ix <= ixhi; ix++)
+        for (int m = 0; m < nvalues; m++)
+          data2d_multi[iy][ix][m] = 0.0;
+
+    for (int iz = izlo; iz <= izhi; iz++)
+      for (int iy = iylo; iy <= iyhi; iy++)
+        for (int ix = ixlo; ix <= ixhi; ix++)
+          data3d_one[iz][iy][ix] = 0.0;
+
+    for (int iz = izlo; iz <= izhi; iz++)
+      for (int iy = iylo; iy <= iyhi; iy++)
+        for (int ix = ixlo; ix <= ixhi; ix++)
+           for (int m = 0; m < nvalues; m++)
+              data3d_multi[iz][iy][ix][m] = 0.0;
+
+Simply replacing the "i" bounds with "o" bounds, also returned by the
+*setup_grid()* method, would alter this code to loop over owned+ghost
+cells (the entire allocated grid).
+
+----------
+
+Grid class constructors
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The following sub-sections describe the public methods of the Grid3d
+class which a style command can invoke.  The Grid2d methods are
+similar; simply remove arguments which refer to the z-dimension.
+
+There are 2 constructors which can be used.  They differ in the extra
+i/o xyz lo/hi arguments:
+
+.. code-block:: c++
+
+   Grid3d(class LAMMPS *lmp, MPI_Comm gcomm, int gnx, int gny, int gnz)
+   Grid3d(class LAMMPS *lmp, MPI_Comm gcomm, int gnx, int gny, int gnz,
+          int ixlo, int ixhi, int iylo, int iyhi, int izlo, int izhi,
+          int oxlo, int oxhi, int oylo, int oyhi, int ozlo, int ozhi)
+
+Both constructors take the LAMMPS instance pointer and a communicator
+over which the grid will be distributed.  Typically this is the
+*world* communicator the LAMMPS instance is using.  The
+:doc:`kspace_style msm <kspace_style>` command creates a series of
+grids, each of different size, which are partitioned across different
+sub-communicators of processors.  Both constructors are also passed
+the global grid size: *gnx* by *gny* by *gnz*.
+
+The first constructor is used when the caller wants the Grid class to
+partition the global grid across processors; the Grid class defines
+which grid cells each processor owns and also which it stores as ghost
+cells.  A subsequent call to *setup_grid()*, discussed below, returns
+this info to the caller.
+
+The second constructor allows the caller to define the extent of owned
+and ghost cells, and pass them to the Grid class.  The 6 arguments
+which start with "i" are the inclusive lower and upper index bounds of
+the owned (inner) grid cells this processor owns in each of the 3
+dimensions within the global grid.  Owned grid cells are indexed from
+0 to N-1 in each dimension.
+
+The 6 arguments which start with "o" are the inclusive bounds of the
+owned+ghost (outer) grid cells it stores.  If the ghost cells are on
+the other side of a periodic boundary, then these indices may be < 0
+or >= N in any dimension, so that oxlo <= ixlo and ixhi >= ixhi is
+always the case.
+
+For example, if Nx = 100, then a processor might pass ixlo=50,
+ixhi=60, oxlo=48, oxhi=62 to the Grid class.  Or ixlo=0, ixhi=10,
+oxlo=-2, oxhi=13.  If a processor owns no grid cells in a dimension,
+then the ihi value should be specified as one less than the ilo value.
+
+Note that the only reason to use the second constructor is if the
+logic for assigning ghost cells is too complex for the Grid class to
+compute, using the various set() methods described next.  Currently
+only the kspace_style pppm/electrode and kspace_style msm commands use
+the second constructor.
+
+----------
+
+Grid class set methods
+^^^^^^^^^^^^^^^^^^^^^^
+
+The following methods affect how the Grid class computes which owned
+and ghost cells are assigned to each processor.  *Set_shift_grid()* is
+the only method which influences owned cell assignment; all the rest
+influence ghost cell assignment.  These methods are only used with the
+first constructor; they are ignored if the second constructor is used.
+These methods must be called before the *setup_grid()* method is
+invoked, because they influence its operation.
+
+.. code-block:: c++
+
+   void set_shift_grid(double shift);
+   void set_distance(double distance);
+   void set_stencil_atom(int lo, int hi);
+   void set_shift_atom(double shift_lo, double shift_hi);
+   void set_stencil_grid(int lo, int hi);
+   void set_zfactor(double factor);
+
+Processors own a grid cell if a point within the grid cell is inside
+the processor's sub-domain.  By default this is the center point of the
+grid cell.  The *set_shift_grid()* method can change this.  The *shift*
+argument is a value from 0.0 to 1.0 (inclusive) which is the offset of
+the point within the grid cell in each dimension.  The default is 0.5
+for the center of the cell.  A value of 0.0 is the lower left corner
+point; a value of 1.0 is the upper right corner point.  There is
+typically no need to change the default as it is optimal for
+minimizing the number of ghost cells needed.
+
+If a processor maps its particles to grid cells, it needs to allow for
+its particles being outside its sub-domain between reneighboring.  The
+*distance* argument of the *set_distance()* method sets the furthest
+distance outside a processor's sub-domain which a particle can move.
+Typically this is half the neighbor skin distance, assuming
+reneighboring is done appropriately.  This distance is used in
+determining how many ghost cells a processor needs to store to enable
+its particles to be mapped to grid cells.  The default value is 0.0.
+
+Some commands, like the :doc:`kspace_style pppm <kspace_style>`
+command, map values (charge in the case of PPPM) to a stencil of grid
+cells beyond the grid cell the particle is in.  The stencil extent may
+be different in the low and high directions.  The *set_stencil_atom()*
+method defines the maximum values of those 2 extents, assumed to be
+the same in each of the 3 dimensions.  Both the lo and hi values are
+specified as positive integers.  The default values are both 0.
+
+Some commands, like the :doc:`kspace_style pppm <kspace_style>`
+command, shift the position of an atom when mapping it to a grid cell,
+based on the size of the stencil used to map values to the grid
+(charge in the case of PPPM).  The lo and hi arguments of the
+*set_shift_atom()* method are the minimum shift in the low direction
+and the maximum shift in the high direction, assumed to be the same in
+each of the 3 dimensions.  The shifts should be fractions of a grid
+cell size with values between 0.0 and 1.0 inclusive.  The default
+values are both 0.0.  See the src/pppm.cpp file for examples of these
+lo/hi values for regular and staggered grids.
+
+Some methods like the :doc:`fix ttm/grid <fix_ttm>` command, perform
+finite difference kinds of operations on the grid, to diffuse electron
+heat in the case of the two-temperature model (TTM).  This operation
+uses ghost grid values beyond the owned grid values the processor
+updates.  The *set_stencil_grid()* method defines the extent of this
+stencil in both directions, assumed to be the same in each of the 3
+dimensions.  Both the lo and hi values are specified as positive
+integers.  The default values are both 0.
+
+The kspace_style pppm commands allow a grid to be defined which
+overlays a volume which extends beyond the simulation box in the z
+dimension.  This is for the purpose of modeling a 2d-periodic slab
+(non-periodic in z) as if it were a larger 3d periodic system,
+extended (with empty space) in the z dimension.  The
+:doc:`kspace_modify slab <kspace_modify>` command is used to specify
+the ratio of the larger volume to the simulation volume; a volume
+ratio of ~3 is typical.  For this kind of model, the PPPM caller sets
+the global grid size *gnz* ~3x larger than it would be otherwise.
+This same ratio is passed by the PPPM caller as the *factor* argument
+to the Grid class via the *set_zfactor()* method (*set_yfactor()* for
+2d grids).  The Grid class will then assign ownership of the 1/3 of
+grid cells that overlay the simulation box to the processors which
+also overlay the simulation box.  The remaining 2/3 of the grid cells
+are assigned to processors whose sub-domains are adjacent to the upper
+z boundary of the simulation box.
+
+----------
+
+Grid class setup_grid method
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The *setup_grid()* method is called after the first constructor
+(above) to partition the grid across processors, which determines
+which grid cells each processor owns.  It also calculates how many
+ghost grid cells in each dimension and each direction each processor
+needs to store.
+
+Note that this method is NOT called if the second constructor above is
+used.  In that case, the caller assigns owned and ghost cells to each
+processor.
+
+Also note that this method must be invoked after any *set_*()* methods have
+been used, since they can influence the assignment of owned and ghost
+cells.
+
+.. code-block:: c++
+
+   void setup_grid(int &ixlo, int &ixhi, int &iylo, int &iyhi, int &izlo, int &izhi,
+                   int &oxlo, int &oxhi, int &oylo, int &oyhi, int &ozlo, int &ozhi)
+
+The 6 return arguments which start with "i" are the inclusive lower
+and upper index bounds of the owned (inner) grid cells this processor
+owns in each of the 3 dimensions within the global grid.  Owned grid
+cells are indexed from 0 to N-1 in each dimension.
+
+The 6 return arguments which start with "o" are the inclusive bounds of
+the owned+ghost cells it owns.  If the ghost cells are on the other
+side of a periodic boundary, then these indices may be < 0 or >= N in
+any dimension, so that oxlo <= ixlo and ixhi >= ixhi is always the
+case.
+
+----------
+
+More grid class set methods
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following 2 methods can be used to override settings made by the
+constructors above.  If used, they must be called called before the
+*setup_comm()* method is invoked, since it uses the settings that
+these methods override.  In LAMMPS these methods are called by by the
+:doc:`kspace_style msm <kspace_style>` command for the grids it
+instantiates using the 2nd constructor above.
+
+.. code-block:: c++
+
+   void set_proc_neighs(int pxlo, int pxhi, int pylo, int pyhi, int pzlo, int pzhi)
+   void set_caller_grid(int fxlo, int fxhi, int fylo, int fyhi, int fzlo, int fzhi)
+
+The *set_proc_neighs()* method sets the processor IDs of the 6
+neighboring processors for each processor.  Normally these would match
+the processor grid neighbors which LAMMPS creates to overlay the
+simulation box (the default).  However, MSM excludes non-participating
+processors from coarse grid communication when less processors are
+used.  This method allows MSM to override the default values.
+
+The *set_caller_grid()* method species the size of the data arrays the
+caller allocates.  Normally these would match the extent of the ghost
+grid cells (the default).  However the MSM caller allocates a larger
+data array (more ghost cells) for its finest-level grid, for use in
+other operations besides owned/ghost cell communication.  This method
+allows MSM to override the default values.
+
+
+----------
+
+Grid class get methods
+^^^^^^^^^^^^^^^^^^^^^^
+
+The following methods allow the caller to query the settings for a
+specific grid, whether it created the grid or another command created
+it.
+
+.. code-block:: c++
+
+   void get_size(int &nxgrid, int &nygrid, int &nzgrid);
+   void get_bounds_owned(int &xlo, int &xhi, int &ylo, int &yhi, int &zlo, int &zhi)
+   void get_bounds_ghost(int &xlo, int &xhi, int &ylo, int &yhi, int &zlo, int &zhi)
+
+The *get_size()* method returns the size of the global grid in each dimension.
+
+The *get_bounds_owned()* method return the inclusive index bounds of
+the grid cells this processor owns.  The values range from 0 to N-1 in
+each dimension.  These values are the same as the "i" values returned
+by *setup_grid()*.
+
+The *get_bounds_ghost()* method return the inclusive index bounds of
+the owned+ghost grid cells this processor stores.  The owned cell
+indices range from 0 to N-1, so these indices may be less than 0 or
+greater than or equal to N in each dimension.  These values are the
+same as the "o" values returned by *setup_grid()*.
+
+----------
+
+Grid class owned/ghost communication
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If needed by the command, the following methods setup and perform
+communication of grid data to/from neighboring processors.  The
+*forward_comm()* method sends owned grid cell data to the
+corresponding ghost grid cells on other processors.  The
+*reverse_comm()* method sends ghost grid cell data to the
+corresponding owned grid cells on another processor.  The caller can
+choose to sum ghost grid cell data to the owned grid cell or simply
+copy it.
+
+.. code-block:: c++
+
+   void setup_comm(int &nbuf1, int &nbuf2)
+   void forward_comm(int caller, void *ptr, int which, int nper, int nbyte,
+                     void *buf1, void *buf2, MPI_Datatype datatype);
+   void reverse_comm(int caller, void *ptr, int which, int nper, int nbyte,
+                     void *buf1, void *buf2, MPI_Datatype datatype)
+   int ghost_adjacent();
+
+The *setup_comm()* method must be called one time before performing
+*forward* or *reverse* communication (multiple times if needed).  It
+returns two integers, which should be used to allocate two buffers.
+The *nbuf1* and *nbuf2* values are the number of grid cells whose data
+will be stored in two buffers by the Grid class when *forward* or
+*reverse* communication is performed.  The caller should thus allocate
+them to a size large enough to hold all the data used in any single
+forward or reverse communication operation it performs.  Note that the
+caller may allocate and communicate multiple data arrays for a grid it
+instantiates.  This size includes the bytes needed for the data type
+of the grid data it stores, e.g. double precision values.
+
+The *forward_comm()* and *reverse_comm()* methods send grid cell data
+from owned to ghost cells, or ghost to owned cells, respectively, as
+described above.  The *caller* argument should be one of these values
+-- Grid3d::COMPUTE, Grid3d::FIX, Grid3d::KSPACE, Grid3d::PAIR --
+depending on the style of the caller class.  The *ptr* argument is the
+"this" pointer to the caller class.  These 2 arguments are used to
+call back to pack()/unpack() functions in the caller class, as
+explained below.
+
+The *which* argument is a flag the caller can set which is passed to
+the caller's pack()/unpack() methods.  This allows a single callback
+method to pack/unpack data for several different flavors of
+forward/reverse communication, e.g. operating on different grids or
+grid data.
+
+The *nper* argument is the number of values per grid cell to be
+communicated.  The *nbyte* argument is the number of bytes per value,
+e.g. 8 for double-precision values.  The *buf1* and *buf2* arguments
+are the two allocated buffers described above.  So long as they are
+allocated for the maximum size communication, they can be re-used for
+any *forward_comm()/reverse_comm()* call.  The *datatype* argument is
+the MPI_Datatype setting, which should match the buffer allocation and
+the *nbyte* argument.  E.g. MPI_DOUBLE for buffers storing double
+precision values.
+
+To use the *forward_grid()* method, the caller must provide two
+callback functions; likewise for use of the *reverse_grid()* methods.
+These are the 4 functions, their arguments are all the same.
+
+.. code-block:: c++
+
+   void pack_forward_grid(int which, void *vbuf, int nlist, int *list);
+   void unpack_forward_grid(int which, void *vbuf, int nlist, int *list);
+   void pack_reverse_grid(int which, void *vbuf, int nlist, int *list);
+   void unpack_reverse_grid(int which, void *vbuf, int nlist, int *list);
+
+The *which* argument is set to the *which* value of the
+*forward_comm()* or *reverse_comm()* calls.  It allows the pack/unpack
+function to select what data values to pack/unpack.  *Vbuf* is the
+buffer to pack/unpack the data to/from.  It is a void pointer so that
+the caller can cast it to whatever data type it chooses, e.g. double
+precision values.  *Nlist* is the number of grid cells to pack/unpack
+and *list* is a vector (nlist in length) of offsets to where the data
+for each grid cell resides in the caller's data arrays, which is best
+illustrated with an example from the src/EXTRA-FIX/fix_ttm_grid.cpp
+class which stores the scalar electron temperature for 3d system in a
+3d grid (one value per grid cell):
+
+.. code-block:: c++
+
+   void FixTTMGrid::pack_forward_grid(int /*which*/, void *vbuf, int nlist, int *list)
+   {
+     auto buf = (double *) vbuf;
+     double *src = &T_electron[nzlo_out][nylo_out][nxlo_out];
+     for (int i = 0; i < nlist; i++) buf[i] = src[list[i]];
+   }
+
+In this case, the *which* argument is not used, *vbuf* points to a
+buffer of doubles, and the electron temperature is stored by the
+FixTTMGrid class in a 3d array of owned+ghost cells called T_electron.
+That array is allocated by the *memory->create_3d_offset()* method
+described above so that the first grid cell it stores is indexed as
+T_electron[nzlo_out][nylo_out][nxlo_out].  The *nlist* values in
+*list* are integer offsets from that first grid cell.  Setting *src*
+to the address of the first cell allows those offsets to be used to
+access the temperatures to pack into the buffer.
+
+Here is a similar portion of code from the src/fix_ave_grid.cpp class
+which can store two kinds of data, a scalar count of atoms in a grid
+cell, and one or more grid-cell-averaged atom properties.  The code
+from its *unpack_reverse_grid()* function for 2d grids and multiple
+per-atom properties per grid cell (*nvalues*) is shown here:
+
+.. code-block:: c++
+
+   void FixAveGrid::unpack_reverse_grid(int /*which*/, void *vbuf, int nlist, int *list)
+   {
+     auto buf = (double *) vbuf;
+     double *count,*data,*values;
+     count = &count2d[nylo_out][nxlo_out];
+     data = &array2d[nylo_out][nxlo_out][0];
+     m = 0;
+     for (i = 0; i < nlist; i++) {
+       count[list[i]] += buf[m++];
+       values = &data[nvalues*list[i]];
+       for (j = 0; j < nvalues; j++)
+        values[j] += buf[m++];
+     }
+   }
+
+Both the count and the multiple values per grid cell are communicated
+in *vbuf*.  Note that *data* is now a pointer to the first value in
+the first grid cell.  And *values* points to where the first value in
+*data* is for an offset of grid cells, calculated by multiplying
+*nvalues* by *list[i]*.  Finally, because this is reverse
+communication, the communicated buffer values are summed to the caller
+values.
+
+The *ghost_adjacent()* method returns a 1 if every processor can
+perform the necessary owned/ghost communication with only its nearest
+neighbor processors (4 in 2d, 6 in 3d).  It returns a 0 if any
+processor's ghost cells extend further than nearest neighbor
+processors.
+
+This can be checked by callers who have the option to change the
+global grid size to insure more efficient nearest-neighbor-only
+communication if they wish.  In this case, they instantiate a grid of
+a given size (resolution), then invoke *setup_comm()* followed by
+*ghost_adjacent()*.  If the ghost cells are not adjacent, they destroy
+the grid instance and start over with a higher-resolution grid.
+Several of the :doc:`kspace_style pppm <kspace_style>` command
+variants have this option.
+
+----------
+
+Grid class remap methods for load balancing
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following methods are used when a load-balancing operation,
+triggered by the :doc:`balance <balance>` or :doc:`fix balance
+<fix_balance>` commands, changes the partitioning of the simulation
+domain into processor sub-domains.
+
+In order to work with load-balancing, any style command (compute, fix,
+pair, or kspace style) which allocates a grid and stores per-grid data
+should define a *reset_grid()* method; it takes no arguments.  It will
+be called by the two balance commands after they have reset processor
+sub-domains and migrated atoms (particles) to new owning processors.
+The *reset_grid()* method will typically perform some or all of the
+following operations.  See the src/fix_ave_grid.cpp and
+src/EXTRA_FIX/fix_ttm_grid.cpp files for examples of *reset_grid()*
+methods, as well as the *pack_remap_grid()* and *unpack_remap_grid()*
+functions.
+
+First, the *reset_grid()* method can instantiate new grid(s) of the
+same global size, then call *setup_grid()* to partition them via the
+new processor sub-domains.  At this point, it can invoke the
+*identical()* method which compares the owned and ghost grid cell
+index bounds between two grids, the old grid passed as a pointer
+argument, and the new grid whose *identical()* method is being called.
+It returns 1 if the indices match on all processors, otherwise 0.  If
+they all match, then the new grids can be deleted; the command can
+continue to use the old grids.
+
+If not, then the command should allocate new grid data array(s) which
+depend on the new partitioning.  If the command does not need to
+persist its grid data from the old partitioning to the new one, then
+the command can simply delete the old data array(s) and grid
+instance(s).  It can then return.
+
+If the grid data does need to persist, then the data for each grid
+needs to be "remapped" from the old grid partitioning to the new grid
+partitioning.  The *setup_remap()* and *remap()* methods are used for
+that purpose.
+
+.. code-block:: c++
+
+   int identical(Grid3d *old);
+   void setup_remap(Grid3d *old, int &nremap_buf1, int &nremap_buf2)
+   void remap(int caller, void *ptr, int which, int nper, int nbyte,
+              void *buf1, void *buf2, MPI_Datatype datatype)
+
+The arguments to these methods are identical to those for
+the *setup_comm()* and *forward_comm()* or *reverse_comm()* methods.
+However the returned *nremap_buf1* and *nremap2_buf* values will be
+different than the *nbuf1* and *nbuf2* values.  They should be used to
+allocate two different remap buffers, separate from the owned/ghost
+communication buffers.
+
+To use the *remap()* method, the caller must provide two
+callback functions:
+
+.. code-block:: c++
+
+   void pack_remap_grid(int which, void *vbuf, int nlist, int *list);
+   void unpack_remap_grid(int which, void *vbuf, int list, int *list);
+
+Their arguments are identical to those for the *pack_forward_grid()*
+and *unpack_forward_grid()* callback functions (or the reverse
+variants) discussed above.  Normally, both these methods pack/unpack
+all the data arrays for a given grid.  The *which* argument of the
+*remap()* method sets the *which* value for the pack/unpack functions.
+If the command instantiates multiple grids (of different sizes), it
+can be used within the pack/unpack methods to select which grid's data
+is being remapped.
+
+Note that the *pack_remap_grid()* function must copy values from the
+OLD grid data arrays into the *vbuf* buffer. The *unpack_remap_grid()*
+function must copy values from the *vbuf* buffer into the NEW grid
+data arrays.
+
+After the remap operation for grid cell data has been performed, the
+*reset_grid()* method can deallocate the two remap buffers it created,
+and can then exit.
+
+----------
+
+Grid class I/O methods
+^^^^^^^^^^^^^^^^^^^^^^
+
+There are two I/O methods in the Grid classes which can be used to
+read and write grid cell data to files.  The caller can decide on the
+precise format of each file, e.g. whether header lines are prepended
+or comment lines are allowed.  Fundamentally, the file should contain
+one line per grid cell for the entire global grid.  Each line should
+contain identifying info as to which grid cell it is, e.g. a unique
+grid cell ID or the ix,iy,iz indices of the cell within a 3d grid.
+The line should also contain one or more data values which are stored
+within the grid data arrays created by the command
+
+For grid cell IDs, the LAMMPS convention is that the IDs run from 1 to
+N, where N = Nx * Ny for 2d grids and N = Nx * Ny * Nz for 3d grids.
+The x-index of the grid cell varies fastest, then y, and the z-index
+varies slowest.  So for a 10x10x10 grid the cell IDs from 901-1000
+would be in the top xy layer of the z dimension.
+
+The *read_file()* method does something simple.  It reads a chunk of
+consecutive lines from the file and passes them back to the caller to
+process.  The caller provides a *unpack_read_grid()* function for this
+purpose.  The function checks the grid cell ID or indices and only
+stores grid cell data for the grid cells it owns.
+
+The *write_file()* method does something slightly more complex.  Each
+processor packs the data for its owned grid cells into a buffer.  The
+caller provides a *pack_write_grid()* function for this purpose.  The
+*write_file()* method then loops over all processors and each sends
+its buffer one at a time to processor 0, along with the 3d (or 2d)
+index bounds of its grid cell data within the global grid.  Processor
+0 calls back to the *unpack_write_grid()* function provided by the
+caller with the buffer.  The function writes one line per grid cell to
+the file.
+
+See the src/EXTRA_FIX/fix_ttm_grid.cpp file for examples of now both
+these methods are used to read/write electron temperature values
+from/to a file, as well as for implementations of the the pack/unpack
+functions described below.
+
+Here are the details of the two I/O methods and the 3 callback
+functions.  See the src/fix_ave_grid.cpp file for examples of all of
+them.
+
+.. code-block:: c++
+
+   void read_file(int caller, void *ptr, FILE *fp, int nchunk, int maxline)
+   void write_file(int caller, void *ptr, int which,
+                   int nper, int nbyte, MPI_Datatype datatype
+
+The *caller* argument in both methods should be one of these values --
+Grid3d::COMPUTE, Grid3d::FIX, Grid3d::KSPACE, Grid3d::PAIR --
+depending on the style of the caller class.  The *ptr* argument in
+both methods is the "this" pointer to the caller class.  These 2
+arguments are used to call back to pack()/unpack() functions in the
+caller class, as explained below.
+
+For the *read_file()* method, the *fp* argument is a file pointer to
+the file to be read from, opened on processor 0 by the caller.
+*Nchunk* is the number of lines to read per chunk, and *maxline* is
+the maximum number of characters per line.  The Grid class will
+allocate a buffer for storing chunks of lines based on these values.
+
+For the *write_file()* method, the *which* argument is a flag the
+caller can set which is passed back to the caller's pack()/unpack()
+methods.  If the command instantiates multiple grids (of different
+sizes), this flag can be used within the pack/unpack methods to select
+which grid's data is being written out (presumably to different
+files).  the *nper* argument is the number of values per grid cell to
+be written out.  The *nbyte* argument is the number of bytes per
+value, e.g. 8 for double-precision values.  The *datatype* argument is
+the MPI_Datatype setting, which should match the *nbyte* argument.
+E.g. MPI_DOUBLE for double precision values.
+
+To use the *read_grid()* method, the caller must provide one callback
+function.  To use the *write_grid()* method, it provides two callback
+functions:
+
+.. code-block:: c++
+
+   int unpack_read_grid(int nlines, char *buffer)
+   void pack_write_grid(int which, void *vbuf)
+   void unpack_write_grid(int which, void *vbuf, int *bounds)
+
+For *unpack_read_grid()* the *nlines* argument is the number of lines
+of character data read from the file and contained in *buffer*.  The
+lines each include a newline character at the end.  When the function
+processes the lines, it may choose to skip some of them (header or
+comment lines).  It returns an integer count of the number of grid
+cell lines it processed.  This enables the Grid class *read_file()*
+method to know when it has read the correct number of lines.
+
+For *pack_write_grid()* and *unpack_write_grid()*, the *vbuf* argument
+is the buffer to pack/unpack data to/from.  It is a void pointer so
+that the caller can cast it to whatever data type it chooses,
+e.g. double precision values.  the *which* argument is set to the
+*which* value of the *write_file()* method.  It allows the caller to
+choose which grid data to operate on.
+
+For *unpack_write_grid()*, the *bounds* argument is a vector of 4 or 6
+integer grid indices (4 for 2d, 6 for 3d).  They are the
+xlo,xhi,ylo,yhi,zlo,zhi index bounds of the portion of the global grid
+which the *vbuf* holds owned grid cell data values for.  The caller
+should loop over the values in *vbuf* with a double loop (2d) or
+triple loop (3d), similar to the code snippets listed above.  The
+x-index varies fastest, then y, and the z-index slowest.  If there are
+multiple values per grid cell, the index for those values varies
+fastest of all.  The caller can add the x,y,z indices of the grid cell
+(or the corresponding grid cell ID) to the data value(s) written as
+one line to the output file.
+
+----------
+
+Style class grid access methods
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A style command can enable its grid cell data to be accessible from
+other commands.  For example :doc:`fix ave/grid <fix_ave_grid>` or
+:doc:`dump grid <dump>` or :doc:`dump grid/vtk <dump>`.  Those
+commands access the grid cell data by using a *grid reference* in
+their input script syntax, as described on the :doc:`Howto_grid
+<Howto_grid>` doc page.  They look like this:
+
+* c_ID:gname:dname
+* c_ID:gname:dname[I]
+* f_ID:gname:dname
+* f_ID:gname:dname[I]
+
+Each grid a command instantiates has a unique *gname*, defined by the
+command.  Likewise each grid cell data structure (scalar or vector)
+associated with a grid has a unique *dname*, also defined by the
+command.
+
+To provide access to its grid cell data, a style command needs to
+implement the following 4 methods:
+
+.. code-block:: c++
+
+   int get_grid_by_name(const std::string &name, int &dim);
+   void *get_grid_by_index(int index);
+   int get_griddata_by_name(int igrid, const std::string &name, int &ncol);
+   void *get_griddata_by_index(int index);
+
+Currently only computes and fixes can implement these methods.  If it
+does so, the compute of fix should also set the variable
+*pergrid_flag* to 1.  See any of the compute or fix commands which set
+"pergrid_flag = 1" for examples of how these 4 functions can be
+implemented.
+
+The *get_grid_by_name()* method takes a grid name as input and returns
+two values.  The *dim* argument is returned as 2 or 3 for the
+dimensionality of the grid.  The function return is a grid index from
+0 to G-1 where *G* is the number of grids the command instantiates.  A
+value of -1 is returned if the grid name is not recognized.
+
+The *get_grid_by_index()* method is called after the
+*get_grid_by_name()* method, using the grid index it returned as its
+argument.  This method will return a pointer to the Grid2d or Grid3d
+class.  The caller can use this to query grid attributes, such as the
+global size of the grid.  The :doc:`dump grid <dump>` to insure each
+its grid reference arguments are for grids of the same size.
+
+The *get_griddata_by_name()* method takes a grid index *igrid* and a
+data name as input.  It returns two values.  The *ncol* argument is
+returned as a 0 if the grid data is a single value (scalar) per grid
+cell, or an integer M > 0 if there are M values (vector) per grid
+cell.  Note that even if M = 1, it is still a 1-length vector, not a
+scalar.  The function return is a data index from 0 to D-1 where *D*
+is the number of data sets associated with that grid by the command.
+A value of -1 is returned if the data name is not recognized.
+
+The *get_griddata_by_index()* method is called after the
+*get_griddata_by_name()* method, using the data index it returned as
+its argument.  This method will return a pointer to the
+multi-dimensional array which stores the requested data.
+
+As in the discussion above of the Memory class *create_offset()*
+methods, the dimensionality of the array associated with the returned
+pointer depends on whether it is a 2d or 3d grid and whether there is
+a single or multiple values stored for each grid cell:
+
+* single value per cell for a 2d grid = 2d array pointer
+* multiple values per cell for a 2d grid = 3d array pointer
+* single value per cell for a 3d grid = 3d array pointer
+* multiple values per cell for a 3d grid = 4d array pointer
+
+The caller will typically access the data by casting the void pointer
+to the corresponding array pointer and using nested loops in x,y,z
+between owned or ghost index bounds returned by the
+*get_bounds_owned()* or *get_bounds_ghost()* methods to index into the
+array.  Example code snippets with this logic were listed above,
+
+----------
+
+Final notes
+^^^^^^^^^^^
+
+Finally, here are some additional issues to pay attention to for
+writing any style command which uses distributed grids via the Grid2d
+or Grid3d class.
+
+The command destructor should delete all instances of the Grid class,
+any buffers it allocated for forward/reverse or remap communication,
+and any data arrays it allocated to store grid cell data.
+
+If a command is intended to work for either 2d or 3d simulations, then
+it should have logic to instantiate either 2d or 3d grids and their
+associated data arrays, depending on the dimension of the simulation
+box.  The :doc:`fix ave/grid <fix_ave_grid>` command is an example of
+such a command.
+
+When a command maps its particles to the grid and updates grid cell
+values, it should check that it is not updating or accessing a grid
+cell value outside the range of its owned+ghost cells, and generate an
+error message if that is the case.  This could happen, for example, if
+a particle has moved further than half the neighbor skin distance,
+because the neighbor list update criterion are not adequate to prevent
+it from happening.  See the src/KSPACE/pppm.cpp file and its
+*particle_map()* method for an example of this kind of error check.

doc/src/Developer_notes.rst

@@ -105,7 +105,7 @@ list, where each pair of atoms is listed only once (except when the
 pairs straddling sub-domains or periodic boundaries will be listed twice).
 Thus these are the default settings when a neighbor list request is created in:
 
-.. code-block:: C++
+.. code-block:: c++
 
    void Pair::init_style()
    {
@@ -129,7 +129,7 @@ neighbor list request to the specific needs of a style an additional
 request flag is needed.  The :doc:`tersoff <pair_tersoff>` pair style,
 for example, needs a "full" neighbor list:
 
-.. code-block:: C++
+.. code-block:: c++
 
    void PairTersoff::init_style()
    {
@@ -141,7 +141,7 @@ When a pair style supports r-RESPA time integration with different cutoff region
 the request flag may depend on the corresponding r-RESPA settings. Here an example
 from pair style lj/cut:
 
-.. code-block:: C++
+.. code-block:: c++
 
    void PairLJCut::init_style()
    {
@@ -160,7 +160,7 @@ Granular pair styles need neighbor lists based on particle sizes and not cutoff
 and also may require to have the list of previous neighbors available ("history").
 For example with:
 
-.. code-block:: C++
+.. code-block:: c++
 
    if (use_history) neighbor->add_request(this, NeighConst::REQ_SIZE | NeighConst::REQ_HISTORY);
    else neighbor->add_request(this, NeighConst::REQ_SIZE);
@@ -170,7 +170,7 @@ settings each request can set an id which is then used in the corresponding
 ``init_list()`` function to assign it to the suitable pointer variable. This is
 done for example by the :doc:`pair style meam <pair_meam>`:
 
-.. code-block:: C++
+.. code-block:: c++
 
    void PairMEAM::init_style()
    {
@@ -189,7 +189,7 @@ just once) and this can also be indicated by a flag.  As an example here
 is the request from the ``FixPeriNeigh`` class which is created
 internally by :doc:`Peridynamics pair styles <pair_peri>`:
 
-.. code-block:: C++
+.. code-block:: c++
 
    neighbor->add_request(this, NeighConst::REQ_FULL | NeighConst::REQ_OCCASIONAL);
 
@@ -198,7 +198,7 @@ than what is usually inferred from the pair style settings (largest cutoff of
 all pair styles plus neighbor list skin).  The following is used in the
 :doc:`compute rdf <compute_rdf>` command implementation:
 
-.. code-block:: C++
+.. code-block:: c++
 
   if (cutflag)
     neighbor->add_request(this, NeighConst::REQ_OCCASIONAL)->set_cutoff(mycutneigh);
@@ -212,7 +212,7 @@ for printing the neighbor list summary the name of the requesting command
 should be set.  Below is the request from the :doc:`delete atoms <delete_atoms>`
 command:
 
-.. code-block:: C++
+.. code-block:: c++
 
    neighbor->add_request(this, "delete_atoms", NeighConst::REQ_FULL);
 

doc/src/Developer_plugins.rst

@@ -95,7 +95,7 @@ a class ``PairMorse2`` in the files ``pair_morse2.h`` and
 ``pair_morse2.cpp`` with the factory function and initialization
 function would look like this:
 
-.. code-block:: C++
+.. code-block:: c++
 
   #include "lammpsplugin.h"
   #include "version.h"
@@ -141,7 +141,7 @@ list of argument strings), then the pointer type is ``lammpsplugin_factory2``
 and it must be assigned to the *creator.v2* member of the plugin struct.
 Below is an example for that:
 
-.. code-block:: C++
+.. code-block:: c++
 
   #include "lammpsplugin.h"
   #include "version.h"
@@ -176,7 +176,7 @@ demonstrated in the following example, which also shows that the
 implementation of the plugin class may be within the same source
 file as the plugin interface code:
 
-.. code-block:: C++
+.. code-block:: c++
 
    #include "lammpsplugin.h"
 

doc/src/Developer_unittest.rst

@@ -194,7 +194,7 @@ macro. These tests operate by capturing the screen output when executing
 the failing command and then comparing that with a provided regular
 expression string pattern.  Example:
 
-.. code-block:: C++
+.. code-block:: c++
 
    TEST_F(SimpleCommandsTest, UnknownCommand)
    {
@@ -226,9 +226,9 @@ The following test programs are currently available:
    * - ``test_kim_commands.cpp``
      - KimCommands
      - Tests for several commands from the :ref:`KIM package <PKG-KIM>`
-   * - ``test_reset_ids.cpp``
+   * - ``test_reset_atoms.cpp``
-     - ResetIDs
+     - ResetAtoms
-     - Tests to validate the :doc:`reset_atom_ids <reset_atom_ids>` and :doc:`reset_mol_ids <reset_mol_ids>` commands
+     - Tests to validate the :doc:`reset_atoms <reset_atoms>` sub-commands
 
 
 Tests for the C-style library interface
@@ -249,7 +249,7 @@ MPI support.  These include tests where LAMMPS is run in multi-partition
 mode or only on a subset of the MPI world communicator.  The CMake
 script code for adding this kind of test looks like this:
 
-.. code-block:: CMake
+.. code-block:: cmake
 
    if (BUILD_MPI)
      add_executable(test_library_mpi test_library_mpi.cpp)

doc/src/Developer_updating.rst

@@ -7,7 +7,7 @@ source files provided as a supplement to a publication) that are written
 for an older version of LAMMPS and thus need to be updated to be
 compatible with the current version of LAMMPS.  Due to the active
 development of LAMMPS it is likely to always be incomplete.  Please
-contact developer@lammps.org in case you run across an issue that is not
+contact developers@lammps.org in case you run across an issue that is not
 (yet) listed here.  Please also review the latest information about the
 LAMMPS :doc:`programming style conventions <Modify_style>`, especially
 if you are considering to submit the updated version for inclusion into
@@ -25,6 +25,7 @@ Available topics in mostly chronological order are:
 - `Simplified and more compact neighbor list requests`_
 - `Split of fix STORE into fix STORE/GLOBAL and fix STORE/PERATOM`_
 - `Use Output::get_dump_by_id() instead of Output::find_dump()`_
+- `Refactored grid communication using Grid3d/Grid2d classes instead of GridComm`_
 
 ----
 
@@ -61,7 +62,7 @@ header file needs to be updated accordingly.
 
 Old:
 
-.. code-block:: C++
+.. code-block:: c++
 
    int PairEAM::pack_comm(int n, int *list, double *buf, int pbc_flag, int *pbc)
    {
@@ -75,7 +76,7 @@ Old:
 
 New:
 
-.. code-block:: C++
+.. code-block:: c++
 
    int PairEAM::pack_forward_comm(int n, int *list, double *buf, int pbc_flag, int *pbc)
    {
@@ -112,14 +113,14 @@ Example from a pair style:
 
 Old:
 
-.. code-block:: C++
+.. code-block:: c++
 
    if (eflag || vflag) ev_setup(eflag, vflag);
    else evflag = vflag_fdotr = eflag_global = eflag_atom = 0;
 
 New:
 
-.. code-block:: C++
+.. code-block:: c++
 
    ev_init(eflag, vflag);
 
@@ -142,14 +143,14 @@ when they are called from only one or a subset of the MPI processes.
 
 Old:
 
-.. code-block:: C++
+.. code-block:: c++
 
     val = force->numeric(FLERR, arg[1]);
     num = force->inumeric(FLERR, arg[2]);
 
 New:
 
-.. code-block:: C++
+.. code-block:: c++
 
     val = utils::numeric(FLERR, true, arg[1], lmp);
     num = utils::inumeric(FLERR, false, arg[2], lmp);
@@ -183,14 +184,14 @@ copy them around for simulations.
 
 Old:
 
-.. code-block:: C++
+.. code-block:: c++
 
    fp = force->open_potential(filename);
    fp = fopen(filename, "r");
 
 New:
 
-.. code-block:: C++
+.. code-block:: c++
 
    fp = utils::open_potential(filename, lmp);
 
@@ -207,7 +208,7 @@ Example:
 
 Old:
 
-.. code-block:: C++
+.. code-block:: c++
 
    if (fptr == NULL) {
      char str[128];
@@ -217,7 +218,7 @@ Old:
 
 New:
 
-.. code-block:: C++
+.. code-block:: c++
 
    if (fptr == nullptr)
      error->one(FLERR, "Cannot open AEAM potential file {}: {}", filename, utils::getsyserror());
@@ -237,7 +238,7 @@ an example from the ``FixWallReflect`` class:
 
 Old:
 
-.. code-block:: C++
+.. code-block:: c++
 
    FixWallReflect(class LAMMPS *, int, char **);
    virtual ~FixWallReflect();
@@ -247,7 +248,7 @@ Old:
 
 New:
 
-.. code-block:: C++
+.. code-block:: c++
 
    FixWallReflect(class LAMMPS *, int, char **);
    ~FixWallReflect() override;
@@ -271,7 +272,7 @@ the type of the "this" pointer argument.
 
 Old:
 
-.. code-block:: C++
+.. code-block:: c++
 
    comm->forward_comm_pair(this);
    comm->forward_comm_fix(this);
@@ -284,7 +285,7 @@ Old:
 
 New:
 
-.. code-block:: C++
+.. code-block:: c++
 
    comm->forward_comm(this);
    comm->reverse_comm(this);
@@ -304,7 +305,7 @@ requests can be :doc:`found here <Developer_notes>`. Example from the
 
 Old:
 
-.. code-block:: C++
+.. code-block:: c++
 
    int irequest = neighbor->request(this,instance_me);
    neighbor->requests[irequest]->pair = 0;
@@ -317,7 +318,7 @@ Old:
 
 New:
 
-.. code-block:: C++
+.. code-block:: c++
 
    auto req = neighbor->add_request(this, NeighConst::REQ_OCCASIONAL);
    if (cutflag) req->set_cutoff(mycutneigh);
@@ -340,7 +341,7 @@ these are internal fixes, there is no user visible change.
 
 Old:
 
-.. code-block:: C++
+.. code-block:: c++
 
    #include "fix_store.h"
 
@@ -351,7 +352,7 @@ Old:
 
 New:
 
-.. code-block:: C++
+.. code-block:: c++
 
    #include "fix_store_peratom.h"
 
@@ -362,7 +363,7 @@ New:
 
 Old:
 
-.. code-block:: C++
+.. code-block:: c++
 
    #include "fix_store.h"
 
@@ -373,7 +374,7 @@ Old:
 
 New:
 
-.. code-block:: C++
+.. code-block:: c++
 
    #include "fix_store_global.h"
 
@@ -396,7 +397,7 @@ the dump directly.  Example:
 
 Old:
 
-.. code-block:: C++
+.. code-block:: c++
 
    int idump = output->find_dump(arg[iarg+1]);
    if (idump < 0)
@@ -412,7 +413,7 @@ Old:
 
 New:
 
-.. code-block:: C++
+.. code-block:: c++
 
    auto idump = output->get_dump_by_id(arg[iarg+1]);
    if (!idump) error->all(FLERR,"Dump ID {} in hyper command does not exist", arg[iarg+1]);
@@ -423,3 +424,56 @@ New:
    if (dumpflag) for (auto idump : dumplist) idump->write();
 
 This change is **required** or else the code will not compile.
+
+Refactored grid communication using Grid3d/Grid2d classes instead of GridComm
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionchanged:: 22Dec2022
+
+The ``GridComm`` class was for creating and communicating distributed
+grids was replaced by the ``Grid3d`` class with added functionality.
+A ``Grid2d`` class was also added for additional flexibility.
+
+The new functionality and commands using the two grid classes are
+discussed on the following documentation pages:
+
+- :doc:`Howto_grid`
+- :doc:`Developer_grid`
+
+If you have custom LAMMPS code, which uses the GridComm class, here are some notes
+on how to adapt it for using the Grid3d class.
+
+(1) The constructor has changed to allow the ``Grid3d`` / ``Grid2d``
+    classes to partition the global grid across processors, both for
+    owned and ghost grid cells.  Previously any class which called
+    ``GridComm`` performed the partitioning itself and that information
+    was passed in the ``GridComm::GridComm()`` constructor.  There are
+    several "set" functions which can be called to alter how ``Grid3d``
+    / ``Grid2d`` perform the partitioning.  They should be sufficient
+    for most use cases of the grid classes.
+
+(2) The partitioning is triggered by the ``setup_grid()`` method.
+
+(3) The ``setup()`` method of the ``GridComm`` class has been replaced
+    by the ``setup_comm()`` method in the new grid classes.  The syntax
+    for the ``forward_comm()`` and ``reverse_comm()`` methods is
+    slightly altered as is the syntax of the associated pack/unpack
+    callback methods.  But the functionality of these operations is the
+    same as before.
+
+(4) The new ``Grid3d`` / ``Grid2d`` classes have additional
+    functionality for dynamic load-balancing of grids and their
+    associated data across processors.  This did not exist in the
+    ``GridComm`` class.
+
+This and more is explained in detail on the :doc:`Developer_grid` page.
+The following LAMMPS source files can be used as illustrative examples
+for how the new grid classes are used by computes, fixes, and various
+KSpace solvers which use distributed FFT grids:
+
+- ``src/fix_ave_grid.cpp``
+- ``src/compute_property_grid.cpp``
+- ``src/EXTRA-FIX/fix_ttm_grid.cpp``
+- ``src/KSPACE/pppm.cpp``
+
+This change is **required** or else the code will not compile.

doc/src/Developer_utils.rst

@@ -133,6 +133,9 @@ and parsing files or arguments.
 .. doxygenfunction:: trim_comment
    :project: progguide
 
+.. doxygenfunction:: strip_style_suffix
+   :project: progguide
+
 .. doxygenfunction:: star_subst
    :project: progguide
 
@@ -211,6 +214,9 @@ Argument processing
 .. doxygenfunction:: expand_args
    :project: progguide
 
+.. doxygenfunction:: parse_grid_id
+   :project: progguide
+
 .. doxygenfunction:: expand_type
    :project: progguide
 
@@ -317,7 +323,7 @@ are all "whitespace" characters, i.e. the space character, the tabulator
 character, the carriage return character, the linefeed character, and
 the form feed character.
 
-.. code-block:: C++
+.. code-block:: c++
    :caption: Tokenizer class example listing entries of the PATH environment variable
 
    #include "tokenizer.h"
@@ -349,7 +355,7 @@ tokenizer into a ``try`` / ``catch`` block to handle errors.  The
 when a (type of) number is requested as next token that is not
 compatible with the string representing the next word.
 
-.. code-block:: C++
+.. code-block:: c++
    :caption: ValueTokenizer class example with exception handling
 
    #include "tokenizer.h"
@@ -427,7 +433,7 @@ one or two array indices "[<number>]" with numbers > 0.
 
 A typical code segment would look like this:
 
-.. code-block:: C++
+.. code-block:: c++
    :caption: Usage example for ArgInfo class
 
    int nvalues = 0;
@@ -476,7 +482,7 @@ open the file, and will call the :cpp:class:`LAMMPS_NS::Error` class in
 case of failures to read or to convert numbers, so that LAMMPS will be
 aborted.
 
-.. code-block:: C++
+.. code-block:: c++
    :caption: Use of PotentialFileReader class in pair style coul/streitz
 
     PotentialFileReader reader(lmp, file, "coul/streitz");
@@ -555,7 +561,7 @@ chunk size needs to be known in advance, 2) with :cpp:func:`MyPage::vget()
 its size is registered later with :cpp:func:`MyPage::vgot()
 <LAMMPS_NS::MyPage::vgot>`.
 
-.. code-block:: C++
+.. code-block:: c++
    :caption: Example of using :cpp:class:`MyPage <LAMMPS_NS::MyPage>`
 
       #include "my_page.h"

doc/src/Developer_write.rst

@@ -26,7 +26,7 @@ constructor with the signature: ``FixPrintVel(class LAMMPS *, int, char **)``.
 Every fix must be registered in LAMMPS by writing the following lines
 of code in the header before include guards:
 
-.. code-block:: c
+.. code-block:: c++
 
    #ifdef FIX_CLASS
    // clang-format off
@@ -47,7 +47,7 @@ keyword when it parses the input script.
 Let's write a simple fix which will print the average velocity at the end
 of each timestep. First of all, implement a constructor:
 
-.. code-block:: C++
+.. code-block:: c++
 
    FixPrintVel::FixPrintVel(LAMMPS *lmp, int narg, char **arg)
    : Fix(lmp, narg, arg)
@@ -72,7 +72,7 @@ in the Fix class called ``nevery`` which specifies how often the method
 
 The next method we need to implement is ``setmask()``:
 
-.. code-block:: C++
+.. code-block:: c++
 
    int FixPrintVel::setmask()
    {
@@ -87,7 +87,7 @@ during execution. The constant ``END_OF_STEP`` corresponds to the
 are called during a timestep and the order in which they are called
 are shown in the previous section.
 
-.. code-block:: C++
+.. code-block:: c++
 
    void FixPrintVel::end_of_step()
    {
@@ -143,7 +143,7 @@ The group membership information of an atom is contained in the *mask*
 property of and atom and the bit corresponding to a given group is
 stored in the groupbit variable which is defined in Fix base class:
 
-.. code-block:: C++
+.. code-block:: c++
 
    for (int i = 0; i < nlocal; ++i) {
      if (atom->mask[i] & groupbit) {
@@ -174,7 +174,7 @@ to store positions of atoms from previous timestep, we need to add
 ``double** xold`` to the header file. Than add allocation code
 to the constructor:
 
-.. code-block:: C++
+.. code-block:: c++
 
    FixSavePos::FixSavePos(LAMMPS *lmp, int narg, char **arg), xold(nullptr)
    {
@@ -190,7 +190,7 @@ to the constructor:
 
 Implement the aforementioned methods:
 
-.. code-block:: C++
+.. code-block:: c++
 
    double FixSavePos::memory_usage()
    {

doc/src/Howto.rst

@@ -51,6 +51,7 @@ Analysis howto
 
    Howto_output
    Howto_chunk
+   Howto_grid
    Howto_temperature
    Howto_elastic
    Howto_kappa

doc/src/Howto_grid.rst

@@ -0,0 +1,102 @@
+Using distributed grids
+=======================
+
+.. versionadded:: 22Dec2022
+
+LAMMPS has internal capabilities to create uniformly spaced grids
+which overlay the simulation domain.  For 2d and 3d simulations these
+are 2d and 3d grids respectively.  Conceptually a grid can be thought
+of as a collection of grid cells.  Each grid cell can store one or
+more values (data).
+
+The grid cells and data they store are distributed across processors.
+Each processor owns the grid cells (and data) whose center points lie
+within the spatial sub-domain of the processor.  If needed for its
+computations, a processor may also store ghost grid cells with their
+data.
+
+Distributed grids can overlay orthogonal or triclinic simulation
+boxes; see the :doc:`Howto triclinic <Howto_triclinic>` doc page for
+an explanation of the latter.  For a triclinic box, the grid cell
+shape conforms to the shape of the simulation domain,
+e.g. parallelograms instead of rectangles in 2d.
+
+If the box size or shape changes during a simulation, the grid changes
+with it, so that it always overlays the entire simulation domain.  For
+non-periodic dimensions, the grid size in that dimension matches the
+box size, as set by the :doc:`boundary <boundary>` command for fixed
+or shrink-wrapped boundaries.
+
+If load-balancing is invoked by the :doc:`balance <balance>` or
+:doc:`fix balance <fix_balance>` commands, then the sub-domain owned
+by a processor can change which may also change which grid cells they
+own.
+
+Post-processing and visualization of grid cell data can be enabled by
+the :doc:`dump grid <dump>`, :doc:`dump grid/vtk <dump>`, and
+:doc:`dump image <dump_image>` commands.  The latter has an optional
+*grid* keyword.  The `OVITO visualization tool
+<https://www.ovito.org>`_ also plans (as of Nov 2022) to add support
+for visualizing grid cell data (along with atoms) using :doc:`dump
+grid <dump>` output files as input.
+
+.. note::
+
+   For developers, distributed grids are implemented within the code via
+   two classes: Grid2d and Grid3d.  These partition the grid across
+   processors and have methods which allow forward and reverse
+   communication of ghost grid data as well as load balancing.  If you
+   write a new compute or fix which needs a distributed grid, these are
+   the classes to look at.  A new pair style could use a distributed
+   grid by having a fix define it.  Please see the section on
+   :doc:`using distributed grids within style classes <Developer_grid>`
+   for a detailed description.
+
+----------
+
+These are the commands which currently define or use distributed
+grids:
+
+* :doc:`fix ttm/grid <fix_ttm>` - store electron temperature on grid
+* :doc:`fix ave/grid <fix_ave_grid>` - time average per-atom or per-grid values
+* :doc:`compute property/grid <compute_property_grid>` - generate grid IDs and coords
+* :doc:`dump grid <dump>` - output per-grid values in LAMMPS format
+* :doc:`dump grid/vtk <dump>` - output per-grid values in VTK format
+* :doc:`dump image grid <dump_image>` - include colored grid in output images
+* :doc:`pair_style amoeba <pair_amoeba>` - FFT grids
+* :doc:`kspace_style pppm <kspace_style>` (and variants) - FFT grids
+* :doc:`kspace_style msm <kspace_style>` (and variants) - MSM grids
+
+The grids used by the :doc:`kspace_style <kspace_style>` can not be
+referenced by an input script.  However the grids and data created and
+used by the other commands can be.
+
+A compute or fix command may create one or more grids (of different
+sizes).  Each grid can store one or more data fields.  A data field
+can be a single value per grid point (per-grid vector) or multiple
+values per grid point (per-grid array).  See the :doc:`Howto output
+<Howto_output>` doc page for an explanation of how per-grid data can
+be generated by some commands and used by other commands.
+
+A command accesses grid data from a compute or fix using a *grid
+reference* with the following syntax:
+
+* c_ID:gname:dname
+* c_ID:gname:dname[I]
+* f_ID:gname:dname
+* f_ID:gname:dname[I]
+
+The prefix "c\_" or "f\_" refers to the ID of the compute or fix; gname is
+the name of the grid, which is assigned by the compute or fix; dname is
+the name of the data field, which is also assigned by the compute or
+fix.
+
+If the data field is a per-grid vector (one value per grid point),
+then no brackets are used to access the values.  If the data field is
+a per-grid array (multiple values per grid point), then brackets are
+used to specify the column I of the array.  I ranges from 1 to Ncol
+inclusive, where Ncol is the number of columns in the array and is
+defined by the compute or fix.
+
+Currently, there are no per-grid variables implemented in LAMMPS.  We
+may add this feature at some point.

doc/src/Howto_output.rst

@@ -22,14 +22,17 @@ commands you specify.
 As discussed below, LAMMPS gives you a variety of ways to determine
 what quantities are computed and printed when the thermodynamics,
 dump, or fix commands listed above perform output.  Throughout this
-discussion, note that users can also :doc:`add their own computes and fixes to LAMMPS <Modify>` which can then generate values that can then be
+discussion, note that users can also :doc:`add their own computes and
-output with these commands.
+fixes to LAMMPS <Modify>` which can then generate values that can then
+be output with these commands.
 
-The following sub-sections discuss different LAMMPS command related
+The following sub-sections discuss different LAMMPS commands related
 to output and the kind of data they operate on and produce:
 
-* :ref:`Global/per-atom/local data <global>`
+* :ref:`Global/per-atom/local/per-grid data <global>`
 * :ref:`Scalar/vector/array data <scalar>`
+* :ref:`Per-grid data <grid>`
+* :ref:`Disambiguation <disambiguation>`
 * :ref:`Thermodynamic output <thermo>`
 * :ref:`Dump file output <dump>`
 * :ref:`Fixes that write output files <fixoutput>`
@@ -42,27 +45,32 @@ to output and the kind of data they operate on and produce:
 
 .. _global:
 
-Global/per-atom/local data
+Global/per-atom/local/per-grid data
---------------------------
+-----------------------------------
 
-Various output-related commands work with three different styles of
+Various output-related commands work with four different styles of
-data: global, per-atom, or local.  A global datum is one or more
+data: global, per-atom, local, and per-grid.  A global datum is one or
-system-wide values, e.g. the temperature of the system.  A per-atom
+more system-wide values, e.g. the temperature of the system.  A
-datum is one or more values per atom, e.g. the kinetic energy of each
+per-atom datum is one or more values per atom, e.g. the kinetic energy
-atom.  Local datums are calculated by each processor based on the
+of each atom.  Local datums are calculated by each processor based on
-atoms it owns, but there may be zero or more per atom, e.g. a list of
+the atoms it owns, but there may be zero or more per atom, e.g. a list
-bond distances.
+of bond distances.
+
+A per-grid datum is one or more values per grid cell, for a grid which
+overlays the simulation domain.  The grid cells and the data they
+store are distributed across processors; each processor owns the grid
+cells whose center point falls within its sub-domain.
 
 .. _scalar:
 
 Scalar/vector/array data
 ------------------------
 
-Global, per-atom, and local datums can each come in three kinds: a
+Global, per-atom, and local datums can come in three kinds: a single
-single scalar value, a vector of values, or a 2d array of values.  The
+scalar value, a vector of values, or a 2d array of values.  The doc
-doc page for a "compute" or "fix" or "variable" that generates data
+page for a "compute" or "fix" or "variable" that generates data will
-will specify both the style and kind of data it produces, e.g. a
+specify both the style and kind of data it produces, e.g. a per-atom
-per-atom vector.
+vector.
 
 When a quantity is accessed, as in many of the output commands
 discussed below, it can be referenced via the following bracket
@@ -83,6 +91,18 @@ the dimension twice (array -> scalar).  Thus a command that uses
 scalar values as input can typically also process elements of a vector
 or array.
 
+.. _grid:
+
+Per-grid data
+------------------------
+
+Per-grid data can come in two kinds: a vector of values (one per grid
+cekk), or a 2d array of values (multiple values per grid ckk).  The
+doc page for a "compute" or "fix" that generates data will specify
+names for both the grid(s) and datum(s) it produces, e.g. per-grid
+vectors or arrays, which can be referenced by other commands.  See the
+:doc:`Howto grid <Howto_grid>` doc page for more details.
+
 .. _disambiguation:
 
 Disambiguation
@@ -90,15 +110,15 @@ Disambiguation
 
 Some computes and fixes produce data in multiple styles, e.g. a global
 scalar and a per-atom vector. Usually the context in which the input
-script references the data determines which style is meant. Example: if
+script references the data determines which style is meant. Example:
-a compute provides both a global scalar and a per-atom vector, the
+if a compute provides both a global scalar and a per-atom vector, the
 former will be accessed by using ``c_ID`` in an equal-style variable,
 while the latter will be accessed by using ``c_ID`` in an atom-style
-variable.  Note that atom-style variable formulas can also access global
+variable.  Note that atom-style variable formulas can also access
-scalars, but in this case it is not possible to do directly because of
+global scalars, but in this case it is not possible to do this
-the ambiguity.  Instead, an equal-style variable can be defined which
+directly because of the ambiguity.  Instead, an equal-style variable
-accesses the global scalar, and that variable used in the atom-style
+can be defined which accesses the global scalar, and that variable can
-variable formula in place of ``c_ID``.
+be used in the atom-style variable formula in place of ``c_ID``.
 
 .. _thermo:
 
@@ -107,15 +127,14 @@ Thermodynamic output
 
 The frequency and format of thermodynamic output is set by the
 :doc:`thermo <thermo>`, :doc:`thermo_style <thermo_style>`, and
-:doc:`thermo_modify <thermo_modify>` commands.  The
+:doc:`thermo_modify <thermo_modify>` commands.  The :doc:`thermo_style
-:doc:`thermo_style <thermo_style>` command also specifies what values
+<thermo_style>` command also specifies what values are calculated and
-are calculated and written out.  Pre-defined keywords can be specified
+written out.  Pre-defined keywords can be specified (e.g. press, etotal,
-(e.g. press, etotal, etc).  Three additional kinds of keywords can
+etc).  Three additional kinds of keywords can also be specified (c_ID,
-also be specified (c_ID, f_ID, v_name), where a :doc:`compute <compute>`
+f_ID, v_name), where a :doc:`compute <compute>` or :doc:`fix <fix>` or
-or :doc:`fix <fix>` or :doc:`variable <variable>` provides the value to be
+:doc:`variable <variable>` provides the value to be output.  In each
-output.  In each case, the compute, fix, or variable must generate
+case, the compute, fix, or variable must generate global values for
-global values for input to the :doc:`thermo_style custom <dump>`
+input to the :doc:`thermo_style custom <dump>` command.
-command.
 
 Note that thermodynamic output values can be "extensive" or
 "intensive".  The former scale with the number of atoms in the system
@@ -141,9 +160,10 @@ There is also a :doc:`dump custom <dump>` format where the user
 specifies what values are output with each atom.  Pre-defined atom
 attributes can be specified (id, x, fx, etc).  Three additional kinds
 of keywords can also be specified (c_ID, f_ID, v_name), where a
-:doc:`compute <compute>` or :doc:`fix <fix>` or :doc:`variable <variable>`
+:doc:`compute <compute>` or :doc:`fix <fix>` or :doc:`variable
-provides the values to be output.  In each case, the compute, fix, or
+<variable>` provides the values to be output.  In each case, the
-variable must generate per-atom values for input to the :doc:`dump custom <dump>` command.
+compute, fix, or variable must generate per-atom values for input to
+the :doc:`dump custom <dump>` command.
 
 There is also a :doc:`dump local <dump>` format where the user specifies
 what local values to output.  A pre-defined index keyword can be
@@ -154,18 +174,23 @@ provides the values to be output.  In each case, the compute or fix
 must generate local values for input to the :doc:`dump local <dump>`
 command.
 
+There is also a :doc:`dump grid <dump>` format where the user
+specifies what per-grid values to output from computes or fixes that
+generate per-grid data.
+
 .. _fixoutput:
 
 Fixes that write output files
 -----------------------------
 
 Several fixes take various quantities as input and can write output
-files: :doc:`fix ave/time <fix_ave_time>`, :doc:`fix ave/chunk <fix_ave_chunk>`, :doc:`fix ave/histo <fix_ave_histo>`,
+files: :doc:`fix ave/time <fix_ave_time>`, :doc:`fix ave/chunk
-:doc:`fix ave/correlate <fix_ave_correlate>`, and :doc:`fix print <fix_print>`.
+<fix_ave_chunk>`, :doc:`fix ave/histo <fix_ave_histo>`, :doc:`fix
+ave/correlate <fix_ave_correlate>`, and :doc:`fix print <fix_print>`.
 
-The :doc:`fix ave/time <fix_ave_time>` command enables direct output to
+The :doc:`fix ave/time <fix_ave_time>` command enables direct output
-a file and/or time-averaging of global scalars or vectors.  The user
+to a file and/or time-averaging of global scalars or vectors.  The
-specifies one or more quantities as input.  These can be global
+user specifies one or more quantities as input.  These can be global
 :doc:`compute <compute>` values, global :doc:`fix <fix>` values, or
 :doc:`variables <variable>` of any style except the atom style which
 produces per-atom values.  Since a variable can refer to keywords used
@@ -184,8 +209,14 @@ atoms, e.g. individual molecules.  The per-atom quantities can be atom
 density (mass or number) or atom attributes such as position,
 velocity, force.  They can also be per-atom quantities calculated by a
 :doc:`compute <compute>`, by a :doc:`fix <fix>`, or by an atom-style
-:doc:`variable <variable>`.  The chunk-averaged output of this fix can
+:doc:`variable <variable>`.  The chunk-averaged output of this fix is
-also be used as input to other output commands.
+global and can also be used as input to other output commands.
+
+Note that the :doc:`fix ave/grid <fix_ave_grid>` command can also
+average the same per-atom quantities within spatial bins, but it does
+this for a distributed grid whose grid cells are owned by different
+processors.  It outputs per-grid data, not global data, so it is more
+efficient for large numbers of averaging bins.
 
 The :doc:`fix ave/histo <fix_ave_histo>` command enables direct output
 to a file of histogrammed quantities, which can be global or per-atom
@@ -202,38 +233,53 @@ written to the screen and log file or to a separate file, periodically
 during a running simulation.  The line can contain one or more
 :doc:`variable <variable>` values for any style variable except the
 vector or atom styles).  As explained above, variables themselves can
-contain references to global values generated by :doc:`thermodynamic keywords <thermo_style>`, :doc:`computes <compute>`,
+contain references to global values generated by :doc:`thermodynamic
-:doc:`fixes <fix>`, or other :doc:`variables <variable>`, or to per-atom
+keywords <thermo_style>`, :doc:`computes <compute>`, :doc:`fixes
-values for a specific atom.  Thus the :doc:`fix print <fix_print>`
+<fix>`, or other :doc:`variables <variable>`, or to per-atom values
-command is a means to output a wide variety of quantities separate
+for a specific atom.  Thus the :doc:`fix print <fix_print>` command is
-from normal thermodynamic or dump file output.
+a means to output a wide variety of quantities separate from normal
+thermodynamic or dump file output.
 
 .. _computeoutput:
 
 Computes that process output quantities
 ---------------------------------------
 
-The :doc:`compute reduce <compute_reduce>` and :doc:`compute reduce/region <compute_reduce>` commands take one or more per-atom
+The :doc:`compute reduce <compute_reduce>` and :doc:`compute
-or local vector quantities as inputs and "reduce" them (sum, min, max,
+reduce/region <compute_reduce>` commands take one or more per-atom or
+local vector quantities as inputs and "reduce" them (sum, min, max,
 ave) to scalar quantities.  These are produced as output values which
 can be used as input to other output commands.
 
-The :doc:`compute slice <compute_slice>` command take one or more global
+The :doc:`compute slice <compute_slice>` command take one or more
-vector or array quantities as inputs and extracts a subset of their
+global vector or array quantities as inputs and extracts a subset of
-values to create a new vector or array.  These are produced as output
+their values to create a new vector or array.  These are produced as
-values which can be used as input to other output commands.
+output values which can be used as input to other output commands.
 
-The :doc:`compute property/atom <compute_property_atom>` command takes a
+The :doc:`compute property/atom <compute_property_atom>` command takes
-list of one or more pre-defined atom attributes (id, x, fx, etc) and
+a list of one or more pre-defined atom attributes (id, x, fx, etc) and
 stores the values in a per-atom vector or array.  These are produced
 as output values which can be used as input to other output commands.
-The list of atom attributes is the same as for the :doc:`dump custom <dump>` command.
+The list of atom attributes is the same as for the :doc:`dump custom
+<dump>` command.
 
-The :doc:`compute property/local <compute_property_local>` command takes
+The :doc:`compute property/local <compute_property_local>` command
-a list of one or more pre-defined local attributes (bond info, angle
+takes a list of one or more pre-defined local attributes (bond info,
-info, etc) and stores the values in a local vector or array.  These
+angle info, etc) and stores the values in a local vector or array.
-are produced as output values which can be used as input to other
+These are produced as output values which can be used as input to
-output commands.
+other output commands.
+
+The :doc:`compute property/grid <compute_property_grid>` command takes
+a list of one or more pre-defined per-grid attributes (id, grid cell
+coords, etc) and stores the values in a per-grid vector or array.
+These are produced as output values which can be used as input to the
+:doc:`dump grid <dump>` command.
+
+The :doc:`compute property/chunk <compute_property_chunk>` command
+takes a list of one or more pre-defined chunk attributes (id, count,
+coords for spatial bins) and stores the values in a global vector or
+array.  These are produced as output values which can be used as input
+to other output commands.
 
 .. _fixprocoutput:
 
@@ -247,18 +293,42 @@ a time.
 The :doc:`fix ave/atom <fix_ave_atom>` command performs time-averaging
 of per-atom vectors.  The per-atom quantities can be atom attributes
 such as position, velocity, force.  They can also be per-atom
-quantities calculated by a :doc:`compute <compute>`, by a
+quantities calculated by a :doc:`compute <compute>`, by a :doc:`fix
-:doc:`fix <fix>`, or by an atom-style :doc:`variable <variable>`.  The
+<fix>`, or by an atom-style :doc:`variable <variable>`.  The
 time-averaged per-atom output of this fix can be used as input to
 other output commands.
 
-The :doc:`fix store/state <fix_store_state>` command can archive one or
+The :doc:`fix store/state <fix_store_state>` command can archive one
-more per-atom attributes at a particular time, so that the old values
+or more per-atom attributes at a particular time, so that the old
-can be used in a future calculation or output.  The list of atom
+values can be used in a future calculation or output.  The list of
-attributes is the same as for the :doc:`dump custom <dump>` command,
+atom attributes is the same as for the :doc:`dump custom <dump>`
-including per-atom quantities calculated by a :doc:`compute <compute>`,
+command, including per-atom quantities calculated by a :doc:`compute
-by a :doc:`fix <fix>`, or by an atom-style :doc:`variable <variable>`.
+<compute>`, by a :doc:`fix <fix>`, or by an atom-style :doc:`variable
-The output of this fix can be used as input to other output commands.
+<variable>`.  The output of this fix can be used as input to other
+output commands.
+
+The :doc:`fix ave/grid <fix_ave_grid>` command performs time-averaging
+of either per-atom or per-grid data.
+
+For per-atom data it performs averaging for the atoms within each grid
+cell, similar to the :doc:`fix ave/chunk <fix_ave_chunk>` command when
+its chunks are defined as regular 2d or 3d bins.  The per-atom
+quantities can be atom density (mass or number) or atom attributes
+such as position, velocity, force.  They can also be per-atom
+quantities calculated by a :doc:`compute <compute>`, by a :doc:`fix
+<fix>`, or by an atom-style :doc:`variable <variable>`.
+
+The chief difference between the :doc:`fix ave/grid <fix_ave_grid>`
+and :doc:`fix ave/chunk <fix_ave_chunk>` commands when used in this
+context is that the former uses a distributed grid, while the latter
+uses a global grid.  Distributed means that each processor owns the
+subset of grid cells within its sub-domain.  Global means that each
+processor owns a copy of the entire grid.  The :doc:`fix ave/grid
+<fix_ave_grid>` command is thus more efficient for large grids.
+
+For per-grid data, the :doc:`fix ave/grid <fix_ave_grid>` command
+takes inputs for grid data produced by other computes or fixes and
+averages the values for each grid point over time.
 
 .. _compute:
 
@@ -266,24 +336,25 @@ Computes that generate values to output
 ---------------------------------------
 
 Every :doc:`compute <compute>` in LAMMPS produces either global or
-per-atom or local values.  The values can be scalars or vectors or
+per-atom or local or per-grid values.  The values can be scalars or
-arrays of data.  These values can be output using the other commands
+vectors or arrays of data.  These values can be output using the other
-described in this section.  The page for each compute command
+commands described in this section.  The page for each compute command
 describes what it produces.  Computes that produce per-atom or local
-values have the word "atom" or "local" in their style name.  Computes
+or per-grid values have the word "atom" or "local" or "grid as the
-without the word "atom" or "local" produce global values.
+last word in their style name.  Computes without the word "atom" or
+"local" or "grid" produce global values.
 
 .. _fix:
 
 Fixes that generate values to output
 ------------------------------------
 
-Some :doc:`fixes <fix>` in LAMMPS produces either global or per-atom or
+Some :doc:`fixes <fix>` in LAMMPS produces either global or per-atom
-local values which can be accessed by other commands.  The values can
+or local or per-grid values which can be accessed by other commands.
-be scalars or vectors or arrays of data.  These values can be output
+The values can be scalars or vectors or arrays of data.  These values
-using the other commands described in this section.  The page for
+can be output using the other commands described in this section.  The
-each fix command tells whether it produces any output quantities and
+page for each fix command tells whether it produces any output
-describes them.
+quantities and describes them.
 
 .. _variable:
 
@@ -300,6 +371,8 @@ computes, fixes, and other variables.  The values generated by
 variables can be used as input to and thus output by the other
 commands described in this section.
 
+Per-grid variables have not (yet) been implemented.
+
 .. _table:
 
 Summary table of output options and data flow between commands
@@ -319,44 +392,52 @@ Also note that, as described above, when a command takes a scalar as
 input, that could be an element of a vector or array.  Likewise a
 vector input could be a column of an array.
 
-+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
-| Command                                                | Input                                        | Output                                    |
+| Command                                                | Input                                        | Output                                             |
-+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
-| :doc:`thermo_style custom <thermo_style>`              | global scalars                               | screen, log file                          |
+| :doc:`thermo_style custom <thermo_style>`              | global scalars                               | screen, log file                                   |
-+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
-| :doc:`dump custom <dump>`                              | per-atom vectors                             | dump file                                 |
+| :doc:`dump custom <dump>`                              | per-atom vectors                             | dump file                                          |
-+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
-| :doc:`dump local <dump>`                               | local vectors                                | dump file                                 |
+| :doc:`dump local <dump>`                               | local vectors                                | dump file                                          |
-+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
-| :doc:`fix print <fix_print>`                           | global scalar from variable                  | screen, file                              |
+| :doc:`dump grid <dump>`                                | per-grid vectors                             | dump file                                          |
-+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
-| :doc:`print <print>`                                   | global scalar from variable                  | screen                                    |
+| :doc:`fix print <fix_print>`                           | global scalar from variable                  | screen, file                                       |
-+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
-| :doc:`computes <compute>`                              | N/A                                          | global/per-atom/local scalar/vector/array |
+| :doc:`print <print>`                                   | global scalar from variable                  | screen                                             |
-+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
-| :doc:`fixes <fix>`                                     | N/A                                          | global/per-atom/local scalar/vector/array |
+| :doc:`computes <compute>`                              | N/A                                          | global/per-atom/local/per-grid scalar/vector/array |
-+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
-| :doc:`variables <variable>`                            | global scalars and vectors, per-atom vectors | global scalar and vector, per-atom vector |
+| :doc:`fixes <fix>`                                     | N/A                                          | global/per-atom/local/per-grid scalar/vector/array |
-+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
-| :doc:`compute reduce <compute_reduce>`                 | per-atom/local vectors                       | global scalar/vector                      |
+| :doc:`variables <variable>`                            | global scalars and vectors, per-atom vectors | global scalar and vector, per-atom vector          |
-+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
-| :doc:`compute slice <compute_slice>`                   | global vectors/arrays                        | global vector/array                       |
+| :doc:`compute reduce <compute_reduce>`                 | per-atom/local vectors                       | global scalar/vector                               |
-+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
-| :doc:`compute property/atom <compute_property_atom>`   | per-atom vectors                             | per-atom vector/array                     |
+| :doc:`compute slice <compute_slice>`                   | global vectors/arrays                        | global vector/array                                |
-+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
-| :doc:`compute property/local <compute_property_local>` | local vectors                                | local vector/array                        |
+| :doc:`compute property/atom <compute_property_atom>`   | N/A                                          | per-atom vector/array                              |
-+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
-| :doc:`fix vector <fix_vector>`                         | global scalars                               | global vector                             |
+| :doc:`compute property/local <compute_property_local>` | N/A                                          | local vector/array                                 |
-+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
-| :doc:`fix ave/atom <fix_ave_atom>`                     | per-atom vectors                             | per-atom vector/array                     |
+| :doc:`compute property/grid <compute_property_grid>`   | N/A                                          | per-grid vector/array                              |
-+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
-| :doc:`fix ave/time <fix_ave_time>`                     | global scalars/vectors                       | global scalar/vector/array, file          |
+| :doc:`compute property/chunk <compute_property_chunk>` | N/A                                          | global vector/array                                |
-+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
-| :doc:`fix ave/chunk <fix_ave_chunk>`                   | per-atom vectors                             | global array, file                        |
+| :doc:`fix vector <fix_vector>`                         | global scalars                               | global vector                                      |
-+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
-| :doc:`fix ave/histo <fix_ave_histo>`                   | global/per-atom/local scalars and vectors    | global array, file                        |
+| :doc:`fix ave/atom <fix_ave_atom>`                     | per-atom vectors                             | per-atom vector/array                              |
-+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
-| :doc:`fix ave/correlate <fix_ave_correlate>`           | global scalars                               | global array, file                        |
+| :doc:`fix ave/time <fix_ave_time>`                     | global scalars/vectors                       | global scalar/vector/array, file                   |
-+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
-| :doc:`fix store/state <fix_store_state>`               | per-atom vectors                             | per-atom vector/array                     |
+| :doc:`fix ave/chunk <fix_ave_chunk>`                   | per-atom vectors                             | global array, file                                 |
-+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
+| :doc:`fix ave/grid <fix_ave_grid>`                     | per-atom vectors or per-grid vectors         | per-grid vector/array                              |
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
+| :doc:`fix ave/histo <fix_ave_histo>`                   | global/per-atom/local scalars and vectors    | global array, file                                 |
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
+| :doc:`fix ave/correlate <fix_ave_correlate>`           | global scalars                               | global array, file                                 |
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
+| :doc:`fix store/state <fix_store_state>`               | per-atom vectors                             | per-atom vector/array                              |
++--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+

doc/src/Howto_pylammps.rst

@@ -152,14 +152,14 @@ Creating a new instance of PyLammps
 To create a PyLammps object you need to first import the class from the lammps
 module. By using the default constructor, a new *lammps* instance is created.
 
-.. code-block:: Python
+.. code-block:: python
 
    from lammps import PyLammps
    L = PyLammps()
 
 You can also initialize PyLammps on top of this existing *lammps* object:
 
-.. code-block:: Python
+.. code-block:: python
 
    from lammps import lammps, PyLammps
    lmp = lammps()
@@ -180,14 +180,14 @@ For instance, let's take the following LAMMPS command:
 In the original interface this command can be executed with the following
 Python code if *L* was a lammps instance:
 
-.. code-block:: Python
+.. code-block:: python
 
    L.command("region box block 0 10 0 5 -0.5 0.5")
 
 With the PyLammps interface, any command can be split up into arbitrary parts
 separated by white-space, passed as individual arguments to a region method.
 
-.. code-block:: Python
+.. code-block:: python
 
    L.region("box block", 0, 10, 0, 5, -0.5, 0.5)
 
@@ -199,14 +199,14 @@ The benefit of this approach is avoiding redundant command calls and easier
 parameterization. In the original interface parameterization needed to be done
 manually by creating formatted strings.
 
-.. code-block:: Python
+.. code-block:: python
 
    L.command("region box block %f %f %f %f %f %f" % (xlo, xhi, ylo, yhi, zlo, zhi))
 
 In contrast, methods of PyLammps accept parameters directly and will convert
 them automatically to a final command string.
 
-.. code-block:: Python
+.. code-block:: python
 
    L.region("box block", xlo, xhi, ylo, yhi, zlo, zhi)
 
@@ -256,7 +256,7 @@ LAMMPS variables can be both defined and accessed via the PyLammps interface.
 
 To define a variable you can use the :doc:`variable <variable>` command:
 
-.. code-block:: Python
+.. code-block:: python
 
    L.variable("a index 2")
 
@@ -265,14 +265,14 @@ A dictionary of all variables is returned by L.variables
 you can access an individual variable by retrieving a variable object from the
 L.variables dictionary by name
 
-.. code-block:: Python
+.. code-block:: python
 
    a = L.variables['a']
 
 The variable value can then be easily read and written by accessing the value
 property of this object.
 
-.. code-block:: Python
+.. code-block:: python
 
    print(a.value)
    a.value = 4
@@ -284,7 +284,7 @@ LAMMPS expressions can be immediately evaluated by using the eval method. The
 passed string parameter can be any expression containing global thermo values,
 variables, compute or fix data.
 
-.. code-block:: Python
+.. code-block:: python
 
    result = L.eval("ke") # kinetic energy
    result = L.eval("pe") # potential energy
@@ -298,7 +298,7 @@ All atoms in the current simulation can be accessed by using the L.atoms list.
 Each element of this list is an object which exposes its properties (id, type,
 position, velocity, force, etc.).
 
-.. code-block:: Python
+.. code-block:: python
 
    # access first atom
    L.atoms[0].id
@@ -311,7 +311,7 @@ position, velocity, force, etc.).
 
 Some properties can also be used to set:
 
-.. code-block:: Python
+.. code-block:: python
 
    # set position in 2D simulation
    L.atoms[0].position = (1.0, 0.0)
@@ -328,7 +328,7 @@ after a run via the L.runs list. This list contains a growing list of run data.
 The first element is the output of the first run, the second element that of
 the second run.
 
-.. code-block:: Python
+.. code-block:: python
 
    L.run(1000)
    L.runs[0] # data of first 1000 time steps
@@ -339,14 +339,14 @@ the second run.
 Each run contains a dictionary of all trajectories. Each trajectory is
 accessible through its thermo name:
 
-.. code-block:: Python
+.. code-block:: python
 
    L.runs[0].thermo.Step # list of time steps in first run
    L.runs[0].thermo.Ke   # list of kinetic energy values in first run
 
 Together with matplotlib plotting data out of LAMMPS becomes simple:
 
-.. code-block:: Python
+.. code-block:: python
 
    import matplotlib.plot as plt
    steps = L.runs[0].thermo.Step
@@ -406,7 +406,7 @@ Four atoms are placed in the simulation and the dihedral potential is applied on
 them using a datafile. Then one of the atoms is rotated along the central axis by
 setting its position from Python, which changes the dihedral angle.
 
-.. code-block:: Python
+.. code-block:: python
 
    phi = [d \* math.pi / 180 for d in range(360)]
 
@@ -439,7 +439,7 @@ Initially, a 2D system is created in a state with minimal energy.
 
 It is then disordered by moving each atom by a random delta.
 
-.. code-block:: Python
+.. code-block:: python
 
    random.seed(27848)
    deltaperturb = 0.2
@@ -458,7 +458,7 @@ It is then disordered by moving each atom by a random delta.
 Finally, the Monte Carlo algorithm is implemented in Python. It continuously
 moves random atoms by a random delta and only accepts certain moves.
 
-.. code-block:: Python
+.. code-block:: python
 
    estart = L.eval("pe")
    elast = estart
@@ -517,7 +517,7 @@ PyLammps can be run in parallel using mpi4py. This python package can be install
 The following is a short example which reads in an existing LAMMPS input file and
 executes it in parallel.  You can find in.melt in the examples/melt folder.
 
-.. code-block:: Python
+.. code-block:: python
 
    from mpi4py import MPI
    from lammps import PyLammps

doc/src/Howto_structured_data.rst

@@ -43,7 +43,7 @@ JSON
      "ke": $(ke)
    }""" file current_state.json screen no
 
-.. code-block:: JSON
+.. code-block:: json
    :caption: current_state.json
 
    {

doc/src/Howto_tip4p.rst

@@ -8,18 +8,28 @@ This site M is located at a fixed distance away from the oxygen along
 the bisector of the HOH bond angle.  A bond style of *harmonic* and an
 angle style of *harmonic* or *charmm* should also be used.
 
-A TIP4P model is run with LAMMPS using either this command
+A TIP4P model is run with LAMMPS using either these commands
 for a cutoff model:
 
+* :doc:`pair_style tip4p/cut <pair_lj_cut_tip4p>`
 * :doc:`pair_style lj/cut/tip4p/cut <pair_lj_cut_tip4p>`
 
-or these two commands for a long-range model:
+or these commands for a long-range model:
 
+* :doc:`pair_style tip4p/long <pair_coul>`
 * :doc:`pair_style lj/cut/tip4p/long <pair_lj_cut_tip4p>`
+* :doc:`pair_style lj/long/tip4p/long <pair_lj_long>`
+* :doc:`pair_style tip4p/long/soft <pair_fep_soft>`
+* :doc:`pair_style lj/cut/tip4p/long/soft <pair_fep_soft>`
 * :doc:`kspace_style pppm/tip4p <kspace_style>`
+* :doc:`kspace_style pppm/disp/tip4p <kspace_style>`
 
-For both models, the bond lengths and bond angles should be held fixed
+The bond lengths and bond angles should be held fixed using the
-using the :doc:`fix shake <fix_shake>` command.
+:doc:`fix shake <fix_shake>` or :doc:`fix rattle <fix_shake>` command,
+unless a parameterization for a flexible TIP4P model is used.  The
+parameter sets listed below are all for rigid TIP4P model variants and
+thus the bond and angle force constants are not used and can be set to
+any legal value; only equilibrium length and angle are used.
 
 These are the additional parameters (in real units) to set for O and H
 atoms and the water molecule to run a rigid TIP4P model with a cutoff
@@ -87,15 +97,16 @@ solver (e.g. Ewald or PPPM in LAMMPS):
 | LJ :math:`\epsilon`, :math:`\sigma` of OH, HH = 0.0
 |
 
-Note that the when using the TIP4P pair style, the neighbor list
+Note that the when using the TIP4P pair style, the neighbor list cutoff
-cutoff for Coulomb interactions is effectively extended by a distance
+for Coulomb interactions is effectively extended by a distance 2 \* (OM
-2 \* (OM distance), to account for the offset distance of the
+distance), to account for the offset distance of the fictitious charges
-fictitious charges on O atoms in water molecules.  Thus it is
+on O atoms in water molecules.  Thus it is typically best in an
-typically best in an efficiency sense to use a LJ cutoff >= Coulomb
+efficiency sense to use a LJ cutoff >= Coulomb cutoff + 2\*(OM
-cutoff + 2\*(OM distance), to shrink the size of the neighbor list.
+distance), to shrink the size of the neighbor list.  This leads to
-This leads to slightly larger cost for the long-range calculation, so
+slightly larger cost for the long-range calculation, so you can test the
-you can test the trade-off for your model.  The OM distance and the LJ
+trade-off for your model.  The OM distance and the LJ and Coulombic
-and Coulombic cutoffs are set in the :doc:`pair_style lj/cut/tip4p/long <pair_lj_cut_tip4p>` command.
+cutoffs are set in the :doc:`pair_style lj/cut/tip4p/long
+<pair_lj_cut_tip4p>` command.
 
 Wikipedia also has a nice article on `water models <https://en.wikipedia.org/wiki/Water_model>`_.
 

doc/src/Howto_triclinic.rst

@@ -144,11 +144,6 @@ does not change the atom positions due to non-periodicity.  In this
 mode, if you tilt the system to extreme angles, the simulation will
 simply become inefficient, due to the highly skewed simulation box.
 
-The limitation on not creating a simulation box with a tilt factor
-skewing the box more than half the distance of the parallel box length
-can be overridden via the :doc:`box <box>` command.  Setting the *tilt*
-keyword to *large* allows any tilt factors to be specified.
-
 Box flips that may occur using the :doc:`fix deform <fix_deform>` or
 :doc:`fix npt <fix_nh>` commands can be turned off using the *flip no*
 option with either of the commands.

doc/src/Library.rst

@@ -2,12 +2,13 @@ LAMMPS Library Interfaces
 *************************
 
 As described on the :doc:`library interface to LAMMPS <Howto_library>`
-page, LAMMPS can be built as a library (static or shared), so that
+page, LAMMPS can be built as a library (static or shared), so that it
-it can be called by another code, used in a :doc:`coupled manner
+can be called by another code, used in a :doc:`coupled manner
 <Howto_couple>` with other codes, or driven through a :doc:`Python
-script <Python_head>`.  Even the LAMMPS standalone executable is
+script <Python_head>`.  The LAMMPS standalone executable itself is
-essentially a thin wrapper on top of the LAMMPS library, creating a
+essentially a thin wrapper on top of the LAMMPS library, which creates a
-LAMMPS instance, processing input and then existing.
+LAMMPS instance, passes the input for processing to that instance, and
+then exits.
 
 Most of the APIs described below are based on C language wrapper
 functions in the files ``src/library.h`` and ``src/library.cpp``, but
@@ -87,6 +88,18 @@ run LAMMPS in serial mode.
    message retrieved <lammps_get_last_error_message>`.  We thus
    recommend enabling C++ exceptions when using the library interface,
 
+.. admonition:: Using the C library interface as a plugin
+   :class: note
+
+   Rather than including the C library directly and link to the LAMMPS
+   library at compile time, you can use the ``liblammpsplugin.h`` header
+   file and the ``liblammpsplugin.c`` C code in the
+   ``examples/COUPLE/plugin`` folder for an interface to LAMMPS that is
+   largely identical to the regular library interface, only that it will
+   load a LAMMPS shared library file at runtime.  This can be useful for
+   applications where the interface to LAMMPS would be an optional
+   feature.
+
 .. warning::
 
    No checks are made on the arguments of the function calls of the C
@@ -163,5 +176,3 @@ The following links provide some examples and references to the C++ API.
    :maxdepth: 1
 
    Cplusplus
-
-

doc/src/Library_config.rst

@@ -39,7 +39,7 @@ crashes within LAMMPS may be recovered from by enabling
 :ref:`exceptions <exceptions>`, avoiding them proactively is a safer
 approach.
 
-.. code-block:: C
+.. code-block:: c
    :caption: Example for using configuration settings functions
 
    #include "library.h"

doc/src/Library_create.rst

@@ -22,7 +22,7 @@ as the "handle" argument in subsequent function calls until that
 instance is destroyed by calling :cpp:func:`lammps_close`.  Here is a
 simple example demonstrating its use:
 
-.. code-block:: C
+.. code-block:: c
 
    #include "library.h"
    #include <stdio.h>

doc/src/Library_execute.rst

@@ -30,7 +30,7 @@ be included in the file or strings, and expansion of variables with
 ``${name}`` or ``$(expression)`` syntax is performed.
 Below is a short example using some of these functions.
 
-.. code-block:: C
+.. code-block:: c
 
    /* define to make the otherwise hidden prototype for "lammps_open()" visible */
    #define LAMMPS_LIB_MPI

doc/src/Library_properties.rst

@@ -32,7 +32,7 @@ indexed accordingly. Per-atom data can change sizes and ordering at
 every neighbor list rebuild or atom sort event as atoms migrate between
 sub-domains and processors.
 
-.. code-block:: C
+.. code-block:: c
 
    #include "library.h"
    #include <stdio.h>

doc/src/Library_utility.rst

@@ -7,6 +7,7 @@ functions.  They do not directly call the LAMMPS library.
 - :cpp:func:`lammps_encode_image_flags`
 - :cpp:func:`lammps_decode_image_flags`
 - :cpp:func:`lammps_set_fix_external_callback`
+- :cpp:func:`lammps_fix_external_get_force`
 - :cpp:func:`lammps_fix_external_set_energy_global`
 - :cpp:func:`lammps_fix_external_set_energy_peratom`
 - :cpp:func:`lammps_fix_external_set_virial_global`
@@ -44,6 +45,11 @@ where such memory buffers were allocated that require the use of
 
 -----------------------
 
+.. doxygenfunction:: lammps_fix_external_get_force
+   :project: progguide
+
+-----------------------
+
 .. doxygenfunction:: lammps_fix_external_set_energy_global
    :project: progguide
 

doc/src/Manual.rst

@@ -42,7 +42,7 @@ descriptions of all commands included in the LAMMPS code.
 .. only:: html
 
    Once you are familiar with LAMMPS, you may want to bookmark
-   :doc:`this page <Commands_all>` since it gives quick access
+   :doc:`this page <Commands_all>` since it gives quick access to
    the documentation for all LAMMPS commands.
 
 .. _lws: https://www.lammps.org

doc/src/Modify_bond.rst

@@ -13,24 +13,65 @@ Here is a brief description of common methods you define in your
 new derived class.  See bond.h, angle.h, dihedral.h, and improper.h
 for details and specific additional methods.
 
-+-----------------------+---------------------------------------------------------------------------------------+
++-----------------------+---------------------------------------------------------------------+
-| init                  | check if all coefficients are set, calls *init_style* (optional)                      |
+| Required              | "pure" methods that *must* be overridden in a derived class         |
-+-----------------------+---------------------------------------------------------------------------------------+
++=======================+=====================================================================+
-| init_style            | check if style specific conditions are met (optional)                                 |
+| compute               | compute the molecular interactions for all listed items             |
-+-----------------------+---------------------------------------------------------------------------------------+
++-----------------------+---------------------------------------------------------------------+
-| compute               | compute the molecular interactions (required)                                         |
+| coeff                 | set coefficients for one type                                       |
-+-----------------------+---------------------------------------------------------------------------------------+
++-----------------------+---------------------------------------------------------------------+
-| settings              | apply global settings for all types (optional)                                        |
+| equilibrium_distance  | length of bond, used by SHAKE (bond styles only)                    |
-+-----------------------+---------------------------------------------------------------------------------------+
++-----------------------+---------------------------------------------------------------------+
-| coeff                 | set coefficients for one type (required)                                              |
+| equilibrium_angle     | opening of angle, used by SHAKE (angle styles only)                 |
-+-----------------------+---------------------------------------------------------------------------------------+
++-----------------------+---------------------------------------------------------------------+
-| equilibrium_distance  | length of bond, used by SHAKE (required, bond only)                                   |
+| write & read_restart  | writes/reads coeffs to restart files                                |
-+-----------------------+---------------------------------------------------------------------------------------+
++-----------------------+---------------------------------------------------------------------+
-| equilibrium_angle     | opening of angle, used by SHAKE (required, angle only)                                |
+| single                | force/r (bond styles only) and energy of a single bond or angle     |
-+-----------------------+---------------------------------------------------------------------------------------+
++-----------------------+---------------------------------------------------------------------+
-| write & read_restart  | writes/reads coeffs to restart files (required)                                       |
+
-+-----------------------+---------------------------------------------------------------------------------------+
+
-| single                | force (bond only) and energy of a single bond or angle (required, bond or angle only) |
++--------------------------------+----------------------------------------------------------------------+
-+-----------------------+---------------------------------------------------------------------------------------+
+| Optional                       | methods that have a default or dummy implementation                  |
-| memory_usage          | tally memory allocated by the style (optional)                                        |
++================================+======================================================================+
-+-----------------------+---------------------------------------------------------------------------------------+
+| init                           | check if all coefficients are set, calls init_style()                |
++--------------------------------+----------------------------------------------------------------------+
+| init_style                     | check if style specific conditions are met                           |
++--------------------------------+----------------------------------------------------------------------+
+| settings                       | apply global settings for all types                                  |
++--------------------------------+----------------------------------------------------------------------+
+| write & read_restart_settings  | writes/reads global style settings to restart files                  |
++--------------------------------+----------------------------------------------------------------------+
+| write_data                     | write corresponding Coeffs section(s) in data file                   |
++--------------------------------+----------------------------------------------------------------------+
+| memory_usage                   | tally memory allocated by the style                                  |
++--------------------------------+----------------------------------------------------------------------+
+| extract                        | provide access to internal data  (bond or angle styles only)         |
++--------------------------------+----------------------------------------------------------------------+
+| reinit                         | reset all type-based parameters, called by fix adapt (bonds only)    |
++--------------------------------+----------------------------------------------------------------------+
+| pack & unpack_forward_comm     | copy data to and from buffer in forward communication (bonds only)   |
++--------------------------------+----------------------------------------------------------------------+
+| pack & unpack_reverse_comm     | copy data to and from buffer in reverse communication (bonds only)   |
++--------------------------------+----------------------------------------------------------------------+
+
+Here is a list of flags or settings that should be set in the
+constructor of the derived class when they differ from the default
+setting.
+
++---------------------------------+------------------------------------------------------------------------------+---------+
+| Name of flag                    | Description                                                                  | default |
++=================================+==============================================================================+=========+
+| writedata                       | 1 if write_data() is implemented                                             | 1       |
++---------------------------------+------------------------------------------------------------------------------+---------+
+| single_extra                    | number of extra single values calculated (bond styles only)                  | 0       |
++---------------------------------+------------------------------------------------------------------------------+---------+
+| partial_flag                    | 1 if bond type can be set to 0 and deleted (bond styles only)                | 0       |
++---------------------------------+------------------------------------------------------------------------------+---------+
+| reinitflag                      | 1 if style has reinit() and is compatible with fix adapt                     | 1       |
++---------------------------------+------------------------------------------------------------------------------+---------+
+| comm_forward                    | size of buffer (in doubles) for forward communication  (bond styles only)    | 0       |
++---------------------------------+------------------------------------------------------------------------------+---------+
+| comm_reverse                    | size of buffer (in doubles) for reverse communication  (bond styles only)    | 0       |
++---------------------------------+------------------------------------------------------------------------------+---------+
+| comm_reverse_off                | size of buffer for reverse communication with newton off (bond styles only)  | 0       |
++---------------------------------+------------------------------------------------------------------------------+---------+

doc/src/Modify_pair.rst

@@ -1,35 +1,121 @@
 Pair styles
 ===========
 
-Classes that compute pairwise interactions are derived from the Pair
+Classes that compute pairwise non-bonded interactions are derived from
-class.  In LAMMPS, pairwise calculation include many-body potentials
+the Pair class.  In LAMMPS, pairwise calculation include many-body
-such as EAM or Tersoff where particles interact without a static bond
+potentials such as EAM, Tersoff, or ReaxFF where particles interact
-topology.  New styles can be created to add new pair potentials to
+without an explicit bond topology but include interactions beyond
-LAMMPS.
+pairwise non-bonded contributions.  New styles can be created to add
+support for additional pair potentials to LAMMPS.  When the
+modifications are small, sometimes it is more effective to derive from
+an existing pair style class.  This latter approach is also used by
+:doc:`Accelerator packages <Speed_packages>` where the accelerated style
+names differ from their base classes by an appended suffix.
 
-Pair_lj_cut.cpp is a simple example of a Pair class, though it
+The file ``src/pair_lj_cut.cpp`` is an example of a Pair class with a
-includes some optional methods to enable its use with rRESPA.
+very simple potential function.  It includes several optional methods to
+enable its use with :doc:`run_style respa <run_style>` and :doc:`compute
+group/group <compute_group_group>`.
 
-Here is a brief description of the class methods in pair.h:
+Here is a brief list of some the class methods in the Pair class that
+*must* be or *may* be overridden in a derived class.
 
 +---------------------------------+---------------------------------------------------------------------+
+| Required                        | "pure" methods that *must* be overridden in a derived class         |
++=================================+=====================================================================+
 | compute                         | workhorse routine that computes pairwise interactions               |
 +---------------------------------+---------------------------------------------------------------------+
-| settings                        | reads the input script line with arguments you define               |
+| settings                        | processes the arguments to the pair_style command                   |
 +---------------------------------+---------------------------------------------------------------------+
-| coeff                           | set coefficients for one i,j type pair                              |
+| coeff                           | set coefficients for one i,j type pair, called from pair_coeff      |
-+---------------------------------+---------------------------------------------------------------------+
-| init_one                        | perform initialization for one i,j type pair                        |
-+---------------------------------+---------------------------------------------------------------------+
-| init_style                      | initialization specific to this pair style                          |
-+---------------------------------+---------------------------------------------------------------------+
-| write & read_restart            | write/read i,j pair coeffs to restart files                         |
-+---------------------------------+---------------------------------------------------------------------+
-| write & read_restart_settings   | write/read global settings to restart files                         |
-+---------------------------------+---------------------------------------------------------------------+
-| single                          | force/r and energy of a single pairwise interaction between 2 atoms |
-+---------------------------------+---------------------------------------------------------------------+
-| compute_inner/middle/outer      | versions of compute used by rRESPA                                  |
 +---------------------------------+---------------------------------------------------------------------+
 
-The inner/middle/outer routines are optional.
++---------------------------------+----------------------------------------------------------------------+
+| Optional                        | methods that have a default or dummy implementation                  |
++=================================+======================================================================+
+| init_one                        | perform initialization for one i,j type pair                         |
++---------------------------------+----------------------------------------------------------------------+
+| init_style                      | style initialization: request neighbor list(s), error checks         |
++---------------------------------+----------------------------------------------------------------------+
+| init_list                       | Neighbor class callback function to pass neighbor list to pair style |
++---------------------------------+----------------------------------------------------------------------+
+| single                          | force/r and energy of a single pairwise interaction between 2 atoms  |
++---------------------------------+----------------------------------------------------------------------+
+| compute_inner/middle/outer      | versions of compute used by rRESPA                                   |
++---------------------------------+----------------------------------------------------------------------+
+| memory_usage                    | return estimated amount of memory used by the pair style             |
++---------------------------------+----------------------------------------------------------------------+
+| modify_params                   | process arguments to pair_modify command                             |
++---------------------------------+----------------------------------------------------------------------+
+| extract                         | provide access to internal scalar or per-type data like cutoffs      |
++---------------------------------+----------------------------------------------------------------------+
+| extract_peratom                 | provide access to internal per-atom data                             |
++---------------------------------+----------------------------------------------------------------------+
+| setup                           | initialization at the beginning of a run                             |
++---------------------------------+----------------------------------------------------------------------+
+| finish                          | called at the end of a run, e.g. to print                            |
++---------------------------------+----------------------------------------------------------------------+
+| write & read_restart            | write/read i,j pair coeffs to restart files                          |
++---------------------------------+----------------------------------------------------------------------+
+| write & read_restart_settings   | write/read global settings to restart files                          |
++---------------------------------+----------------------------------------------------------------------+
+| write_data                      | write Pair Coeffs section to data file                               |
++---------------------------------+----------------------------------------------------------------------+
+| write_data_all                  | write PairIJ Coeffs section to data file                             |
++---------------------------------+----------------------------------------------------------------------+
+| pack & unpack_forward_comm      | copy data to and from buffer if style uses forward communication     |
++---------------------------------+----------------------------------------------------------------------+
+| pack & unpack_reverse_comm      | copy data to and from buffer if style uses reverse communication     |
++---------------------------------+----------------------------------------------------------------------+
+| reinit                          | reset all type-based parameters, called by fix adapt for example     |
++---------------------------------+----------------------------------------------------------------------+
+| reset_dt                        | called when the time step is changed by timestep or fix reset/dt     |
++---------------------------------+----------------------------------------------------------------------+
+
+Here is a list of flags or settings that should be set in the
+constructor of the derived pair class when they differ from the default
+setting.
+
++---------------------------------+-------------------------------------------------------------+---------+
+| Name of flag                    | Description                                                 | default |
++=================================+=============================================================+=========+
+| single_enable                   | 1 if single() method is implemented, 0 if missing           | 1       |
++---------------------------------+-------------------------------------------------------------+---------+
+| respa_enable                    | 1 if pair style has compute_inner/middle/outer()            | 0       |
++---------------------------------+-------------------------------------------------------------+---------+
+| restartinfo                     | 1 if pair style writes its settings to a restart            | 1       |
++---------------------------------+-------------------------------------------------------------+---------+
+| one_coeff                       | 1 if only a pair_coeff * * command is allowed               | 0       |
++---------------------------------+-------------------------------------------------------------+---------+
+| manybody_flag                   | 1 if pair style is a manybody potential                     | 0       |
++---------------------------------+-------------------------------------------------------------+---------+
+| unit_convert_flag               | value != 0 indicates support for unit conversion            | 0       |
++---------------------------------+-------------------------------------------------------------+---------+
+| no_virial_fdotr_compute         | 1 if pair style does not call virial_fdotr_compute()        | 0       |
++---------------------------------+-------------------------------------------------------------+---------+
+| writedata                       | 1 if write_data() and write_data_all() are implemented      | 0       |
++---------------------------------+-------------------------------------------------------------+---------+
+| comm_forward                    | size of buffer (in doubles) for forward communication       | 0       |
++---------------------------------+-------------------------------------------------------------+---------+
+| comm_reverse                    | size of buffer (in doubles) for reverse communication       | 0       |
++---------------------------------+-------------------------------------------------------------+---------+
+| ghostneigh                      | 1 if cutghost is set and style uses neighbors of ghosts     | 0       |
++---------------------------------+-------------------------------------------------------------+---------+
+| finitecutflag                   | 1 if cutoff depends on diameter of atoms                    | 0       |
++---------------------------------+-------------------------------------------------------------+---------+
+| reinitflag                      | 1 if style has reinit() and is compatible with fix adapt    | 0       |
++---------------------------------+-------------------------------------------------------------+---------+
+| ewaldflag                       | 1 if compatible with kspace_style ewald                     | 0       |
++---------------------------------+-------------------------------------------------------------+---------+
+| pppmflag                        | 1 if compatible with kspace_style pppm                      | 0       |
++---------------------------------+-------------------------------------------------------------+---------+
+| msmflag                         | 1 if compatible with kspace_style msm                       | 0       |
++---------------------------------+-------------------------------------------------------------+---------+
+| dispersionflag                  | 1 if compatible with ewald/disp or pppm/disp                | 0       |
++---------------------------------+-------------------------------------------------------------+---------+
+| tip4pflag                       | 1 if compatible with kspace_style pppm/tip4p                | 0       |
++---------------------------------+-------------------------------------------------------------+---------+
+| dipoleflag                      | 1 if compatible with dipole kspace_style                    | 0       |
++---------------------------------+-------------------------------------------------------------+---------+
+| spinflag                        | 1 if compatible with spin kspace_style                      | 0       |
++---------------------------------+-------------------------------------------------------------+---------+

doc/src/Modify_style.rst

@@ -359,6 +359,12 @@ you are uncertain, please ask.
 
 - I/O is done via the C-style stdio library and **not** iostreams.
 
+- Do not use so-called "alternative tokens" like ``and``, ``or``,
+  ``not`` and similar, but rather use the corresponding operators
+  ``&&``, ``||``, and ``!``.  The alternative tokens are not available
+  by default on all compilers, and also we want to maintain a consistent
+  programming style.
+
 - Output to the screen and the logfile should be using the corresponding
   FILE pointers and only be done on MPI rank 0.  Use the :cpp:func:`utils::logmesg`
   convenience function where possible.

doc/src/Packages_details.rst

@@ -80,6 +80,7 @@ page gives those details.
    * :ref:`ML-HDNNP <PKG-ML-HDNNP>`
    * :ref:`ML-IAP <PKG-ML-IAP>`
    * :ref:`ML-PACE <PKG-ML-PACE>`
+   * :ref:`ML-POD <PKG-ML-POD>`
    * :ref:`ML-QUIP <PKG-ML-QUIP>`
    * :ref:`ML-RANN <PKG-ML-RANN>`
    * :ref:`ML-SNAP <PKG-ML-SNAP>`
@@ -200,6 +201,7 @@ particle models including ellipsoids, 2d lines, and 3d triangles.
 * :doc:`Howto spherical <Howto_spherical>`
 * :doc:`pair_style gayberne <pair_gayberne>`
 * :doc:`pair_style resquared <pair_resquared>`
+* :doc:`pair_style ylz <pair_ylz>`
 * `doc/PDF/pair_gayberne_extra.pdf <PDF/pair_gayberne_extra.pdf>`_
 * `doc/PDF/pair_resquared_extra.pdf <PDF/pair_resquared_extra.pdf>`_
 * examples/ASPHERE
@@ -864,7 +866,7 @@ ELECTRODE package
 The ELECTRODE package allows the user to enforce a constant potential method for
 groups of atoms that interact with the remaining atoms as electrolyte.
 
-**Authors:** The ELECTRODE library is written and maintained by Ludwig
+**Authors:** The ELECTRODE package is written and maintained by Ludwig
 Ahrens-Iwers (TUHH, Hamburg, Germany), Shern Tee (UQ, Brisbane, Australia) and
 Robert Meissner (TUHH, Hamburg, Germany).
 
@@ -877,7 +879,7 @@ This package has :ref:`specific installation instructions <electrode>` on the
 
 **Supporting info:**
 
-* :doc:`fix electrode/conp <fix_electrode_conp>`
+* :doc:`fix electrode/conp <fix_electrode>`
 
 ----------
 
@@ -1484,8 +1486,9 @@ MC package
 
 Several fixes and a pair style that have Monte Carlo (MC) or MC-like
 attributes.  These include fixes for creating, breaking, and swapping
-bonds, for performing atomic swaps, and performing grand-canonical MC
+bonds, for performing atomic swaps, and performing grand canonical
-(GCMC) or similar processes in conjunction with dynamics.
+MC (GCMC), semi-grand canonical MC (SGCMC), or similar processes in
+conjunction with molecular dynamics (MD).
 
 **Supporting info:**
 
@@ -1497,6 +1500,7 @@ bonds, for performing atomic swaps, and performing grand-canonical MC
 * :doc:`fix bond/swap <fix_bond_swap>`
 * :doc:`fix charge/regulation <fix_charge_regulation>`
 * :doc:`fix gcmc <fix_gcmc>`
+* :doc:`fix sgcmc <fix_sgcmc>`
 * :doc:`fix tfmc <fix_tfmc>`
 * :doc:`fix widom <fix_widom>`
 * :doc:`pair_style dsmc <pair_dsmc>`
@@ -1736,8 +1740,6 @@ must be installed.
 
 .. versionadded:: 30Jun2020
 
-   .. versionadded:: 30Jun2020
-
 **Supporting info:**
 
 * src/ML-IAP: filenames -> commands
@@ -1797,6 +1799,39 @@ This package has :ref:`specific installation instructions <ml-pace>` on the
 
 ----------
 
+.. _PKG-ML-POD:
+
+ML-POD package
+-------------------
+
+**Contents:**
+
+A pair style and fitpod style for Proper Orthogonal Descriptors
+(POD). POD is a methodology for deriving descriptors based on the proper
+orthogonal decomposition. The ML-POD package provides an efficient
+implementation for running simulations with POD potentials, along with
+fitting the potentials natively in LAMMPS.
+
+**Authors:**
+
+Ngoc Cuong Nguyen (MIT), Andrew Rohskopf (Sandia)
+
+.. versionadded:: 22Dec2022
+
+**Install:**
+
+This package has :ref:`specific installation instructions <ml-pod>` on the
+:doc:`Build extras <Build_extras>` page.
+
+**Supporting info:**
+
+* src/ML-POD: filenames -> commands
+* :doc:`pair_style pod <pair_pod>`
+* :doc:`command_style fitpod <fitpod_command>`
+* examples/PACKAGES/pod
+
+----------
+
 .. _PKG-ML-QUIP:
 
 ML-QUIP package

doc/src/Packages_list.rst

@@ -155,7 +155,7 @@ whether an extra library is needed to build and use the package:
      - no
    * - :ref:`ELECTRODE <PKG-ELECTRODE>`
      - electrode charges to match potential
-     - :doc:`fix electrode/conp <fix_electrode_conp>`
+     - :doc:`fix electrode/conp <fix_electrode>`
      - PACKAGES/electrode
      - no
    * - :ref:`EXTRA-COMPUTE <PKG-EXTRA-COMPUTE>`
@@ -298,6 +298,11 @@ whether an extra library is needed to build and use the package:
      - :doc:`pair pace <pair_pace>`
      - PACKAGES/pace
      - ext
+   * - :ref:`ML-POD <PKG-ML-POD>`
+     - Proper orthogonal decomposition potentials
+     - :doc:`pair pod <pair_pod>`
+     - pod
+     - ext
    * - :ref:`ML-QUIP <PKG-ML-QUIP>`
      - QUIP/libatoms interface
      - :doc:`pair_style quip <pair_quip>`

doc/src/Python_atoms.rst

@@ -58,7 +58,7 @@ against invalid accesses.
       Each element of this list is a :py:class:`Atom <lammps.Atom>` or :py:class:`Atom2D <lammps.Atom2D>` object. The attributes of
       these objects provide access to their data (id, type, position, velocity, force, etc.):
 
-      .. code-block:: Python
+      .. code-block:: python
 
          # access first atom
          L.atoms[0].id
@@ -71,7 +71,7 @@ against invalid accesses.
 
       Some attributes can be changed:
 
-      .. code-block:: Python
+      .. code-block:: python
 
          # set position in 2D simulation
          L.atoms[0].position = (1.0, 0.0)

doc/src/Python_config.rst

@@ -4,7 +4,7 @@ Configuration information
 The following methods can be used to query the LAMMPS library
 about compile time settings and included packages and styles.
 
-.. code-block:: Python
+.. code-block:: python
    :caption: Example for using configuration settings functions
 
    from lammps import lammps

doc/src/Python_create.rst

@@ -74,7 +74,7 @@ Here are simple examples using all three Python interfaces:
       :py:class:`PyLammps <lammps.PyLammps>` objects can also be created on top of an existing
       :py:class:`lammps <lammps.lammps>` object:
 
-      .. code-block:: Python
+      .. code-block:: python
 
          from lammps import lammps, PyLammps
          ...
@@ -113,7 +113,7 @@ Here are simple examples using all three Python interfaces:
 
       You can also initialize IPyLammps on top of an existing :py:class:`lammps` or :py:class:`PyLammps` object:
 
-      .. code-block:: Python
+      .. code-block:: python
 
          from lammps import lammps, IPyLammps
          ...
@@ -142,7 +142,7 @@ the MPI and/or Kokkos environment if enabled and active.
 Note that you can create multiple LAMMPS objects in your Python
 script, and coordinate and run multiple simulations, e.g.
 
-.. code-block:: Python
+.. code-block:: python
 
    from lammps import lammps
    lmp1 = lammps()

doc/src/Python_error.rst

@@ -7,7 +7,7 @@ current Python process with an error message.  C++ exceptions allow capturing
 them on the C++ side and rethrowing them on the Python side. This way
 LAMMPS errors can be handled through the Python exception handling mechanism.
 
-.. code-block:: Python
+.. code-block:: python
 
    from lammps import lammps, MPIAbortException
 

doc/src/Python_execute.rst

@@ -60,7 +60,7 @@ it is possible to "compute" what the next LAMMPS command should be.
       can be executed using with the lammps API with the following Python code if ``lmp`` is an
       instance of :py:class:`lammps <lammps.lammps>`:
 
-      .. code-block:: Python
+      .. code-block:: python
 
          from lammps import lammps
 
@@ -73,7 +73,7 @@ it is possible to "compute" what the next LAMMPS command should be.
       The arguments of the command can be passed as one string, or
       individually.
 
-      .. code-block:: Python
+      .. code-block:: python
 
          from lammps import PyLammps
 
@@ -93,14 +93,14 @@ it is possible to "compute" what the next LAMMPS command should be.
       parameterization. In the lammps API parameterization needed to be done
       manually by creating formatted command strings.
 
-      .. code-block:: Python
+      .. code-block:: python
 
          lmp.command("region box block %f %f %f %f %f %f" % (xlo, xhi, ylo, yhi, zlo, zhi))
 
       In contrast, methods of PyLammps accept parameters directly and will convert
       them automatically to a final command string.
 
-      .. code-block:: Python
+      .. code-block:: python
 
          L.region("box block", xlo, xhi, ylo, yhi, zlo, zhi)
 

doc/src/Python_launch.rst

@@ -56,7 +56,7 @@ and you should see the same output as if you had typed
 
 Note that without the mpi4py specific lines from ``test.py``
 
-.. code-block:: Python
+.. code-block:: python
 
    from lammps import lammps
    lmp = lammps()

doc/src/Python_objects.rst

@@ -76,7 +76,7 @@ computes, fixes, or variables in LAMMPS using the :py:mod:`lammps` module.
 
       To define a variable you can use the :doc:`variable <variable>` command:
 
-      .. code-block:: Python
+      .. code-block:: python
 
          L.variable("a index 2")
 
@@ -85,14 +85,14 @@ computes, fixes, or variables in LAMMPS using the :py:mod:`lammps` module.
       you can access an individual variable by retrieving a variable object from the
       ``L.variables`` dictionary by name
 
-      .. code-block:: Python
+      .. code-block:: python
 
          a = L.variables['a']
 
       The variable value can then be easily read and written by accessing the value
       property of this object.
 
-      .. code-block:: Python
+      .. code-block:: python
 
          print(a.value)
          a.value = 4

doc/src/Python_properties.rst

@@ -105,7 +105,7 @@ against invalid accesses.
       variables, compute or fix data (see :doc:`Howto_output`):
 
 
-      .. code-block:: Python
+      .. code-block:: python
 
          result = L.eval("ke") # kinetic energy
          result = L.eval("pe") # potential energy

doc/src/Python_scatter.rst

@@ -1,7 +1,7 @@
 Scatter/gather operations
 =========================
 
-.. code-block:: Python
+.. 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
@@ -42,7 +42,7 @@ For the scatter methods, the array of coordinates passed to must be a
 ctypes vector of ints or doubles, allocated and initialized something
 like this:
 
-.. code-block:: Python
+.. code-block:: python
 
    from ctypes import c_double
    natoms = lmp.get_natoms()

doc/src/Run_options.rst

@@ -262,6 +262,8 @@ Disable generating a citation reminder (see above) at all.
 
 **-nonbuf**
 
+.. versionadded:: 15Sep2022
+
 Turn off buffering for screen and logfile output.  For performance
 reasons, output to the screen and logfile is usually buffered, i.e.
 output is only written to a file if its buffer - typically 4096 bytes -
@@ -442,7 +444,7 @@ the LAMMPS simulation domain.
 
 .. _restart2data:
 
-**-restart2data restartfile [remap] datafile keyword value ...**
+**-restart2data restartfile datafile keyword value ...**
 
 Convert the restart file into a data file and immediately exit.  This
 is the same operation as if the following 2-line input script were
@@ -450,7 +452,7 @@ run:
 
 .. code-block:: LAMMPS
 
-   read_restart restartfile [remap]
+   read_restart restartfile
    write_data datafile keyword value ...
 
 The specified restartfile and/or datafile name may contain the wild-card
@@ -462,28 +464,21 @@ Note that a filename such as file.\* may need to be enclosed in quotes or
 the "\*" character prefixed with a backslash ("\") to avoid shell
 expansion of the "\*" character.
 
-Following restartfile argument, the optional word "remap" may be used.
+The syntax following restartfile, namely
-This has the same effect like adding it to a
-:doc:`read_restart <read_restart>` command, and operates as explained on
-its doc page.  This is useful if reading the restart file triggers an
-error that atoms have been lost.  In that case, use of the remap flag
-should allow the data file to still be produced.
-
-The syntax following restartfile (or remap), namely
 
 .. parsed-literal::
 
    datafile keyword value ...
 
 is identical to the arguments of the :doc:`write_data <write_data>`
-command.  See its page for details.  This includes its
+command.  See its documentation page for details.  This includes its
 optional keyword/value settings.
 
 ----------
 
 .. _restart2dump:
 
-**-restart2dump restartfile [remap] group-ID dumpstyle dumpfile arg1 arg2 ...**
+**-restart2dump restartfile group-ID dumpstyle dumpfile arg1 arg2 ...**
 
 Convert the restart file into a dump file and immediately exit.  This
 is the same operation as if the following 2-line input script were
@@ -491,7 +486,7 @@ run:
 
 .. code-block:: LAMMPS
 
-   read_restart restartfile [remap]
+   read_restart restartfile
    write_dump group-ID dumpstyle dumpfile arg1 arg2 ...
 
 Note that the specified restartfile and dumpfile names may contain
@@ -503,24 +498,17 @@ such as file.\* may need to be enclosed in quotes or the "\*" character
 prefixed with a backslash ("\") to avoid shell expansion of the "\*"
 character.
 
-Note that following the restartfile argument, the optional word "remap"
+The syntax following restartfile, namely
-can be used.  This has the effect as adding it to the
-:doc:`read_restart <read_restart>` command, as explained on its doc page.
-This is useful if reading the restart file triggers an error that atoms
-have been lost.  In that case, use of the remap flag should allow the
-dump file to still be produced.
-
-The syntax following restartfile (or remap), namely
 
 .. code-block:: LAMMPS
 
    group-ID dumpstyle dumpfile arg1 arg2 ...
 
 is identical to the arguments of the :doc:`write_dump <write_dump>`
-command.  See its page for details.  This includes what per-atom
+command.  See its documentation page for details.  This includes what
-fields are written to the dump file and optional dump_modify settings,
+per-atom fields are written to the dump file and optional dump_modify
-including ones that affect how parallel dump files are written, e.g.
+settings, including ones that affect how parallel dump files are written,
-the *nfile* and *fileper* keywords.  See the
+e.g. the *nfile* and *fileper* keywords.  See the
 :doc:`dump_modify <dump_modify>` page for details.
 
 ----------

doc/src/Run_output.rst

@@ -16,46 +16,47 @@ simulation.  An example set of statistics is shown here:
 
 .. parsed-literal::
 
-   Loop time of 2.81192 on 4 procs for 300 steps with 2004 atoms
+   Loop time of 0.942801 on 4 procs for 300 steps with 2004 atoms
 
-   Performance: 18.436 ns/day  1.302 hours/ns  106.689 timesteps/s
+   Performance: 54.985 ns/day, 0.436 hours/ns, 318.201 timesteps/s, 637.674 katom-step/s
-   97.0% CPU use with 4 MPI tasks x no OpenMP threads
+   195.2% CPU use with 2 MPI tasks x 2 OpenMP threads
 
-   MPI task timings breakdown:
+   MPI task timing breakdown:
    Section \|  min time  \|  avg time  \|  max time  \|%varavg\| %total
    ---------------------------------------------------------------
-   Pair    \| 1.9808     \| 2.0134     \| 2.0318     \|   1.4 \| 71.60
+   Pair    \| 0.61419    \| 0.62872    \| 0.64325    \|   1.8 \| 66.69
-   Bond    \| 0.0021894  \| 0.0060319  \| 0.010058   \|   4.7 \|  0.21
+   Bond    \| 0.0028608  \| 0.0028899  \| 0.002919   \|   0.1 \|  0.31
-   Kspace  \| 0.3207     \| 0.3366     \| 0.36616    \|   3.1 \| 11.97
+   Kspace  \| 0.12652    \| 0.14048    \| 0.15444    \|   3.7 \| 14.90
-   Neigh   \| 0.28411    \| 0.28464    \| 0.28516    \|   0.1 \| 10.12
+   Neigh   \| 0.10242    \| 0.10242    \| 0.10242    \|   0.0 \| 10.86
-   Comm    \| 0.075732   \| 0.077018   \| 0.07883    \|   0.4 \|  2.74
+   Comm    \| 0.026753   \| 0.027593   \| 0.028434   \|   0.5 \|  2.93
-   Output  \| 0.00030518 \| 0.00042665 \| 0.00078821 \|   1.0 \|  0.02
+   Output  \| 0.00018341 \| 0.00030942 \| 0.00043542 \|   0.0 \|  0.03
-   Modify  \| 0.086606   \| 0.086631   \| 0.086668   \|   0.0 \|  3.08
+   Modify  \| 0.039117   \| 0.039348   \| 0.039579   \|   0.1 \|  4.17
-   Other   \|            \| 0.007178   \|            \|       \|  0.26
+   Other   \|            \| 0.001041   \|            \|       \|  0.11
 
-   Nlocal:    501 ave 508 max 490 min
+   Nlocal:           1002 ave        1006 max         998 min
-   Histogram: 1 0 0 0 0 0 1 1 0 1
+   Histogram: 1 0 0 0 0 0 0 0 0 1
-   Nghost:    6586.25 ave 6628 max 6548 min
+   Nghost:         8670.5 ave        8691 max        8650 min
-   Histogram: 1 0 1 0 0 0 1 0 0 1
+   Histogram: 1 0 0 0 0 0 0 0 0 1
-   Neighs:    177007 ave 180562 max 170212 min
+   Neighs:         354010 ave      357257 max      350763 min
-   Histogram: 1 0 0 0 0 0 0 1 1 1
+   Histogram: 1 0 0 0 0 0 0 0 0 1
 
-   Total # of neighbors = 708028
+   Total # of neighbors = 708020
-   Ave neighs/atom = 353.307
+   Ave neighs/atom = 353.30339
-   Ave special neighs/atom = 2.34032
+   Ave special neighs/atom = 2.3403194
    Neighbor list builds = 26
    Dangerous builds = 0
 
 ----------
 
-The first section provides a global loop timing summary. The *loop
+The first section provides a global loop timing summary. The *loop time*
-time* is the total wall-clock time for the simulation to run.  The
+is the total wall-clock time for the simulation to run.  The
-*Performance* line is provided for convenience to help predict how
+*Performance* line is provided for convenience to help predict how long
-long it will take to run a desired physical simulation.  The *CPU use*
+it will take to run a desired physical simulation and to have numbers
-line provides the CPU utilization per MPI task; it should be close to
+useful for performance comparison between different simulation settings
-100% times the number of OpenMP threads (or 1 of not using OpenMP).
+or system sizes.  The *CPU use* line provides the CPU utilization per
-Lower numbers correspond to delays due to file I/O or insufficient
+MPI task; it should be close to 100% times the number of OpenMP threads
-thread utilization.
+(or 1 of not using OpenMP).  Lower numbers correspond to delays due to
+file I/O or insufficient thread utilization.
 
 ----------
 

doc/src/Speed_kokkos.rst

@@ -212,14 +212,15 @@ threads/task as Nt. The product of these two values should be N, i.e.
 .. note::
 
    The default for the :doc:`package kokkos <package>` command when
-   running on KNL is to use "half" neighbor lists and set the Newton flag
+   running on KNL is to use "half" neighbor lists and set the Newton
-   to "on" for both pairwise and bonded interactions. This will typically
+   flag to "on" for both pairwise and bonded interactions. This will
-   be best for many-body potentials. For simpler pairwise potentials, it
+   typically be best for many-body potentials. For simpler pairwise
-   may be faster to use a "full" neighbor list with Newton flag to "off".
+   potentials, it may be faster to use a "full" neighbor list with
-   Use the "-pk kokkos" :doc:`command-line switch <Run_options>` to change
+   Newton flag to "off".  Use the "-pk kokkos" :doc:`command-line switch
-   the default :doc:`package kokkos <package>` options. See its page for
+   <Run_options>` to change the default :doc:`package kokkos <package>`
-   details and default settings. Experimenting with its options can provide
+   options. See its documentation page for details and default
-   a speed-up for specific calculations. For example:
+   settings. Experimenting with its options can provide a speed-up for
+   specific calculations. For example:
 
 .. code-block:: bash
 
@@ -271,17 +272,18 @@ one or more nodes, each with two GPUs:
 .. note::
 
    The default for the :doc:`package kokkos <package>` command when
-   running on GPUs is to use "full" neighbor lists and set the Newton flag
+   running on GPUs is to use "full" neighbor lists and set the Newton
-   to "off" for both pairwise and bonded interactions, along with threaded
+   flag to "off" for both pairwise and bonded interactions, along with
-   communication. When running on Maxwell or Kepler GPUs, this will
+   threaded communication. When running on Maxwell or Kepler GPUs, this
-   typically be best. For Pascal GPUs and beyond, using "half" neighbor lists and
+   will typically be best. For Pascal GPUs and beyond, using "half"
-   setting the Newton flag to "on" may be faster. For many pair styles,
+   neighbor lists and setting the Newton flag to "on" may be faster. For
-   setting the neighbor binsize equal to twice the CPU default value will
+   many pair styles, setting the neighbor binsize equal to twice the CPU
-   give speedup, which is the default when running on GPUs. Use the "-pk
+   default value will give speedup, which is the default when running on
-   kokkos" :doc:`command-line switch <Run_options>` to change the default
+   GPUs. Use the "-pk kokkos" :doc:`command-line switch <Run_options>`
-   :doc:`package kokkos <package>` options. See its page for details and
+   to change the default :doc:`package kokkos <package>` options. See
-   default settings. Experimenting with its options can provide a speed-up
+   its documentation page for details and default
-   for specific calculations. For example:
+   settings. Experimenting with its options can provide a speed-up for
+   specific calculations. For example:
 
 .. code-block:: bash
 

doc/src/Tools.rst

@@ -57,7 +57,7 @@ Pre-processing tools
    * :ref:`msi2lmp <msi>`
    * :ref:`polybond <polybond>`
    * :ref:`stl_bin2txt <stlconvert>`
-
+   * :ref:`tabulate <tabulate>`
 
 Post-processing tools
 =====================
@@ -1159,13 +1159,27 @@ For illustration purposes below is a part of the Tcl example script.
 
 ----------
 
+.. _tabulate:
+
+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.
+
+----------
+
 .. _vim:
 
 vim tool
 ------------------
 
-The files in the tools/vim directory are add-ons to the VIM editor
+The files in the ``tools/vim`` directory are add-ons to the VIM editor
-that allow easier editing of LAMMPS input scripts.  See the README.txt
+that allow easier editing of LAMMPS input scripts.  See the ``README.txt``
 file for details.
 
 These files were provided by Gerolf Ziegenhain (gerolf at

doc/src/angle_gaussian.rst

@@ -25,23 +25,25 @@ The *gaussian* angle style uses the potential:
 
 .. math::
 
-   E = -k_B T ln\left(\sum_{i=1}^{n} \frac{A_i}{w_i \sqrt{\pi/2}} exp\left( \frac{-(\theta-\theta_{i})^2}{w_i^2})\right) \right)
+   E = -k_B T ln\left(\sum_{i=1}^{n} \frac{A_i}{w_i \sqrt{\pi/2}} exp\left( \frac{-2(\theta-\theta_{i})^2}{w_i^2}\right) \right)
+
+This analytical form is a suitable potential for obtaining mesoscale
+effective force fields which can reproduce target atomistic
+distributions :ref:`(Milano) <Milano1>`.
 
-This analytical form is a suitable potential for obtaining
-mesoscale effective force fields which can reproduce target atomistic distributions :ref:`(Milano) <Milano1>`
 The following coefficients must be defined for each angle type via the
 :doc:`angle_coeff <angle_coeff>` command as in the example above, or in
 the data file or restart files read by the :doc:`read_data <read_data>`
 or :doc:`read_restart <read_restart>` commands:
 
-* T temperature at which the potential was derived
+* :math:`T` temperature at which the potential was derived
 * :math:`n` (integer >=1)
-* :math:`A_1` (-)
+* :math:`A_1` (> 0, radians)
-* :math:`w_1` (-)
+* :math:`w_1` (> 0, radians)
 * :math:`\theta_1` (degrees)
 * ...
-* :math:`A_n` (-)
+* :math:`A_n` (> 0, radians)
-* :math:`w_n` (-)
+* :math:`w_n` (> 0, radians)
 * :math:`\theta_n` (degrees)
 
 

doc/src/angle_table.rst

@@ -59,6 +59,10 @@ format of this file is described below.
 
 ----------
 
+Suitable tables for use with this angle style can be created using the
+Python code in the ``tools/tabulate`` folder of the LAMMPS source code
+distribution.
+
 The format of a tabulated file is as follows (without the
 parenthesized comments):
 

doc/src/bond_bpm_rotational.rst

@@ -45,6 +45,8 @@ Examples
 Description
 """""""""""
 
+.. versionadded:: 4May2022
+
 The *bpm/rotational* bond style computes forces and torques based on
 deviations from the initial reference state of the two atoms.  The
 reference state is stored by each bond when it is first computed in
@@ -67,7 +69,7 @@ which is proportional to the tangential shear displacement with a
 stiffness of :math:`k_s`. This tangential force also induces a torque.
 In addition, bending and twisting torques are also applied to
 particles which are proportional to angular bending and twisting
-displacements with stiffnesses of :math`k_b` and :math:`k_t',
+displacements with stiffnesses of :math:`k_b` and :math:`k_t`,
 respectively.  Details on the calculations of shear displacements and
 angular displacements can be found in :ref:`(Wang) <Wang2009>` and
 :ref:`(Wang and Mora) <Wang2009b>`.
@@ -211,9 +213,9 @@ command, as *b1*, *b2*, ..., *b7*\ .
 Restrictions
 """"""""""""
 
-This bond style can only be used if LAMMPS was built with the BPM
+This bond style is part of the BPM package.  It is only enabled if
-package. See the :doc:`Build package <Build_package>` doc page for
+LAMMPS was built with that package.  See the :doc:`Build package
-more info.
+<Build_package>` page for more info.
 
 By default if pair interactions are to be disabled, this bond style
 requires setting

doc/src/bond_bpm_spring.rst

@@ -45,6 +45,8 @@ Examples
 Description
 """""""""""
 
+.. versionadded:: 4May2022
+
 The *bpm/spring* bond style computes forces and torques based on
 deviations from the initial reference state of the two atoms.  The
 reference state is stored by each bond when it is first computed in
@@ -167,9 +169,9 @@ extra quantity can be accessed by the
 Restrictions
 """"""""""""
 
-This bond style can only be used if LAMMPS was built with the BPM
+This bond style is part of the BPM package.  It is only enabled if
-package. See the :doc:`Build package <Build_package>` doc page for
+LAMMPS was built with that package.  See the :doc:`Build package
-more info.
+<Build_package>` page for more info.
 
 By default if pair interactions are to be disabled, this bond style
 requires setting

doc/src/bond_gaussian.rst

@@ -25,33 +25,34 @@ The *gaussian* bond style uses the potential:
 
 .. math::
 
-   E = -k_B T ln\left(\sum_{i=1}^{n} \frac{A_i}{w_i \sqrt{\pi/2}} exp\left( \frac{-(r-r_{i})^2}{w_i^2})\right) \right)
+   E = -k_B T ln\left(\sum_{i=1}^{n} \frac{A_i}{w_i \sqrt{\pi/2}} exp\left( \frac{-2(r-r_{i})^2}{w_i^2}\right)\right)
 
-This analytical form is a suitable potential for obtaining
+This analytical form is a suitable potential for obtaining mesoscale
-mesoscale effective force fields which can reproduce target atomistic distributions :ref:`(Milano) <Milano0>`
+effective force fields which can reproduce target atomistic
+distributions :ref:`(Milano) <Milano0>`
 
 The following coefficients must be defined for each bond type via the
 :doc:`bond_coeff <bond_coeff>` command as in the example above, or in
 the data file or restart files read by the :doc:`read_data <read_data>`
 or :doc:`read_restart <read_restart>` commands:
 
-* T temperature at which the potential was derived
+* :math:`T` temperature at which the potential was derived
 * :math:`n` (integer >=1)
-* :math:`A_1` (-)
+* :math:`A_1` (> 0, distance)
-* :math:`w_1` (-)
+* :math:`w_1` (> 0, distance)
-* :math:`r_1` (length)
+* :math:`r_1` (>= 0, distance)
 * ...
-* :math:`A_n` (-)
+* :math:`A_n` (> 0, distance)
-* :math:`w_n` (-)
+* :math:`w_n` (> 0, distance)
-* :math:`r_n` (length)
+* :math:`r_n` (>= 0, distance)
 
 
 Restrictions
 """"""""""""
 
 This bond style can only be used if LAMMPS was built with the
-EXTRA-MOLECULE package.  See the :doc:`Build package <Build_package>` doc
+EXTRA-MOLECULE package.  See the :doc:`Build package <Build_package>`
-page for more info.
+doc page for more info.
 
 Related commands
 """"""""""""""""

doc/src/bond_table.rst

@@ -59,6 +59,13 @@ this file is described below.
 
 ----------
 
+Suitable tables for use with this bond style can be created by LAMMPS
+itself from existing bond styles using the :doc:`bond_write
+<bond_write>` command.  This can be useful to have a template file for
+testing the bond style settings and to build a compatible custom file.
+Another option to generate tables is the Python code in the
+``tools/tabulate`` folder of the LAMMPS source code distribution.
+
 The format of a tabulated file is as follows (without the
 parenthesized comments):
 
@@ -149,7 +156,8 @@ info.
 Related commands
 """"""""""""""""
 
-:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
+:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`,
+:doc:`bond_write <bond_write>`
 
 Default
 """""""

doc/src/box.rst

@@ -1,70 +0,0 @@
-.. index:: box
-
-box command
-===========
-
-Syntax
-""""""
-
-.. code-block:: LAMMPS
-
-   box keyword value ...
-
-* one or more keyword/value pairs may be appended
-* keyword = *tilt*
-
-  .. parsed-literal::
-
-       *tilt* value = *small* or *large*
-
-Examples
-""""""""
-
-.. code-block:: LAMMPS
-
-   box tilt large
-   box tilt small
-
-Description
-"""""""""""
-
-Set attributes of the simulation box.
-
-For triclinic (non-orthogonal) simulation boxes, the *tilt* keyword
-allows simulation domains to be created with arbitrary tilt factors,
-e.g. via the :doc:`create_box <create_box>` or
-:doc:`read_data <read_data>` commands.  Tilt factors determine how
-skewed the triclinic box is; see the :doc:`Howto triclinic <Howto_triclinic>` page for a discussion of triclinic
-boxes in LAMMPS.
-
-LAMMPS normally requires that no tilt factor can skew the box more
-than half the distance of the parallel box length, which is the first
-dimension in the tilt factor (x for xz).  If *tilt* is set to
-*small*, which is the default, then an error will be
-generated if a box is created which exceeds this limit.  If *tilt*
-is set to *large*, then no limit is enforced.  You can create
-a box with any tilt factors you wish.
-
-Note that if a simulation box has a large tilt factor, LAMMPS will run
-less efficiently, due to the large volume of communication needed to
-acquire ghost atoms around a processor's irregular-shaped sub-domain.
-For extreme values of tilt, LAMMPS may also lose atoms and generate an
-error.
-
-Restrictions
-""""""""""""
-
-This command cannot be used after the simulation box is defined by a
-:doc:`read_data <read_data>` or :doc:`create_box <create_box>` command or
-:doc:`read_restart <read_restart>` command.
-
-Related commands
-""""""""""""""""
-
-none
-
-
-Default
-"""""""
-
-The default value is tilt = small.

doc/src/clear.rst

@@ -23,15 +23,16 @@ Description
 """""""""""
 
 This command deletes all atoms, restores all settings to their default
-values, and frees all memory allocated by LAMMPS.  Once a clear
+values, and frees all memory allocated by LAMMPS.  Once a clear command
-command has been executed, it is almost as if LAMMPS were starting
+has been executed, it is almost as if LAMMPS were starting over, with
-over, with only the exceptions noted below.  This command enables
+only the exceptions noted below.  This command enables multiple jobs to
-multiple jobs to be run sequentially from one input script.
+be run sequentially from one input script.
 
 These settings are not affected by a clear command: the working
-directory (:doc:`shell <shell>` command), log file status
+directory (:doc:`shell <shell>` command), log file status (:doc:`log
-(:doc:`log <log>` command), echo status (:doc:`echo <echo>` command), and
+<log>` command), echo status (:doc:`echo <echo>` command), and input
-input script variables (:doc:`variable <variable>` command).
+script variables except for *atomfile* style variables (:doc:`variable
+<variable>` command).
 
 Restrictions
 """"""""""""

doc/src/commands_list.rst

@@ -13,7 +13,6 @@ Commands
    bond_style
    bond_write
    boundary
-   box
    change_box
    clear
    comm_modify
@@ -43,6 +42,7 @@ Commands
    echo
    fix
    fix_modify
+   fitpod_command
    group
    group2ndx
    hyper
@@ -90,8 +90,7 @@ Commands
    region
    replicate
    rerun
-   reset_atom_ids
+   reset_atoms
-   reset_mol_ids
    reset_timestep
    restart
    run

doc/src/compute.rst

@@ -43,29 +43,38 @@ underscores.
 
 ----------
 
-Computes calculate one of three styles of quantities: global,
+Computes calculate one or more of four styles of quantities: global,
-per-atom, or local.  A global quantity is one or more system-wide
+per-atom, local, or per-atom.  A global quantity is one or more
-values (e.g., the temperature of the system).  A per-atom quantity is
+system-wide values, e.g. the temperature of the system.  A per-atom
-one or more values per atom (e.g., the kinetic energy of each atom).
+quantity is one or more values per atom, e.g. the kinetic energy of
-Per-atom values are set to 0.0 for atoms not in the specified compute
+each atom.  Per-atom values are set to 0.0 for atoms not in the
-group.  Local quantities are calculated by each processor based on the
+specified compute group.  Local quantities are calculated by each
-atoms it owns, but there may be zero or more per atom (e.g., a list of
+processor based on the atoms it owns, but there may be zero or more
-bond distances).  Computes that produce per-atom quantities have the
+per atom, e.g. a list of bond distances.  Per-grid quantities are
-word "atom" in their style (e.g., *ke/atom*\ ).  Computes that produce
+calculated on a regular 2d or 3d grid which overlays a 2d or 3d
-local quantities have the word "local" in their style
+simulation domain.  The grid points and the data they store are
-(e.g., *bond/local*\ ).  Styles with neither "atom" or "local" in their
+distributed across processors; each processor owns the grid points
-style produce global quantities.
+which fall within its sub-domain.
 
-Note that a single compute can produce either global or per-atom or
+Computes that produce per-atom quantities have the word "atom" at the
-local quantities, but not both global and per-atom.  It can produce
+end of their style, e.g. *ke/atom*\ .  Computes that produce local
-local quantities in tandem with global or per-atom quantities.  The
+quantities have the word "local" at the end of their style,
-compute page will explain.
+e.g. *bond/local*\ .  Computes that produce per-grid quantities have
+the word "grid" at the end of their style, e.g. *property/grid*\ .
+Styles with neither "atom" or "local" or "grid" at the end of their
+style name produce global quantities.
 
-Global, per-atom, and local quantities each come in three kinds: a
+Note that a single compute typically produces either global or
-single scalar value, a vector of values, or a 2d array of values.  The
+per-atom or local or per-grid values.  It does not compute both global
-doc page for each compute describes the style and kind of values it
+and per-atom values.  It can produce local values or per-grid values
-produces (e.g., a per-atom vector).  Some computes produce more than one
+in tandem with global or per-atom quantities.  The compute doc page
-kind of a single style (e.g., a global scalar and a global vector).
+will explain the details.
+
+Global, per-atom, local, and per-grid quantities come in three kinds:
+a single scalar value, a vector of values, or a 2d array of values.
+The doc page for each compute describes the style and kind of values
+it produces, e.g. a per-atom vector.  Some computes produce more than
+one kind of a single style, e.g. a global scalar and a global vector.
 
 When a compute quantity is accessed, as in many of the output commands
 discussed below, it can be referenced via the following bracket
@@ -252,7 +261,8 @@ The individual style names on the :doc:`Commands compute <Commands_compute>` pag
 * :doc:`pressure/uef <compute_pressure_uef>` - pressure tensor in the reference frame of an applied flow field
 * :doc:`property/atom <compute_property_atom>` - convert atom attributes to per-atom vectors/arrays
 * :doc:`property/chunk <compute_property_chunk>` - extract various per-chunk attributes
-* :doc:`property/local <compute_property_local>` - convert local attributes to localvectors/arrays
+* :doc:`property/grid <compute_property_grid>` - convert per-grid attributes to per-grid vectors/arrays
+* :doc:`property/local <compute_property_local>` - convert local attributes to local vectors/arrays
 * :doc:`ptm/atom <compute_ptm_atom>` - determines the local lattice structure based on the Polyhedral Template Matching method
 * :doc:`rdf <compute_rdf>` - radial distribution function :math:`g(r)` histogram of group of atoms
 * :doc:`reduce <compute_reduce>` - combine per-atom quantities into a single global value

doc/src/compute_modify.rst

@@ -37,27 +37,29 @@ Description
 Modify one or more parameters of a previously defined compute.  Not
 all compute styles support all parameters.
 
-The *extra/dof* or *extra* keyword refers to how many degrees of freedom are
+The *extra/dof* or *extra* keyword refers to how many degrees of
-subtracted (typically from :math:`3N`) as a normalizing
+freedom are subtracted (typically from :math:`3N`) as a normalizing
 factor in a temperature computation.  Only computes that compute a
-temperature use this option.  The default is 2 or 3 for
+temperature use this option.  The default is 2 or 3 for :doc:`2d or 3d
-:doc:`2d or 3d systems <dimension>`, which is a correction factor for an
+systems <dimension>` which is a correction factor for an ensemble of
-ensemble of velocities with zero total linear momentum. For compute
+velocities with zero total linear momentum. For compute temp/partial,
-temp/partial, if one or more velocity components are excluded, the
+if one or more velocity components are excluded, the value used for
-value used for *extra* is scaled accordingly. You can use a negative
+*extra* is scaled accordingly. You can use a negative number for the
-number for the *extra* parameter if you need to add
+*extra* parameter if you need to add degrees-of-freedom.  See the
-degrees-of-freedom.  See the :doc:`compute temp/asphere <compute_temp_asphere>` command for an example.
+:doc:`compute temp/asphere <compute_temp_asphere>` command for an
+example.
 
 The *dynamic/dof* or *dynamic* keyword determines whether the number
-of atoms :math:`N` in the compute group and their associated degrees of
+of atoms :math:`N` in the compute group and their associated degrees
-freedom (DOF) are re-computed each time a temperature is computed.  Only
+of freedom (DOF) are re-computed each time a temperature is computed.
-compute styles that calculate a temperature use this option.  By
+Only compute styles that calculate a temperature use this option.  By
-default, :math:`N` and their DOF are assumed to be constant.  If you are
+default, :math:`N` and their DOF are assumed to be constant.  If you
-adding atoms or molecules to the system (see the :doc:`fix pour <fix_pour>`,
+are adding atoms or molecules to the system (see the :doc:`fix pour
-:doc:`fix deposit <fix_deposit>`, and :doc:`fix gcmc <fix_gcmc>` commands) or
+<fix_pour>`, :doc:`fix deposit <fix_deposit>`, and :doc:`fix gcmc
-expect atoms or molecules to be lost (e.g., due to exiting the simulation box
+<fix_gcmc>` commands) or expect atoms or molecules to be lost
-or via :doc:`fix evaporate <fix_evaporate>`), then this option should be used
+(e.g. due to exiting the simulation box or via :doc:`fix evaporate
-to ensure the temperature is correctly normalized.
+<fix_evaporate>`), then this option should be used to insure the
+temperature is correctly normalized.
 
 .. note::
 

doc/src/compute_nbond_atom.rst

@@ -23,6 +23,8 @@ Examples
 Description
 """""""""""
 
+.. versionadded:: 4May2022
+
 Define a computation that computes the number of bonds each atom is
 part of.  Bonds which are broken are not counted in the tally.  See
 the :doc:`Howto broken bonds <Howto_bpm>` page for more information.
@@ -40,8 +42,9 @@ LAMMPS output options.
 Restrictions
 """"""""""""
 
-This fix can only be used if LAMMPS was built with the BPM package.
+This compute is part of the BPM package.  It is only enabled if LAMMPS was
-See the :doc:`Build package <Build_package>` doc page for more info.
+built with that package.  See the :doc:`Build package <Build_package>`
+page for more info.
 
 Related commands
 """"""""""""""""

doc/src/compute_pair_local.rst

@@ -59,7 +59,7 @@ 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 lower to the one with the higher id.
+distance from the atom of higher to the one with the lower atom ID.
 
 The value *eng* is the interaction energy for the pair of atoms.
 

doc/src/compute_property_chunk.rst

@@ -12,7 +12,8 @@ Syntax
 
 * ID, group-ID are documented in :doc:`compute <compute>` command
 * property/chunk = style name of this compute command
-* input = one or more attributes
+* chunkID = ID of :doc:`compute chunk/atom <compute_chunk_atom>` command that defines the chunks
+* input1,etc = one or more attributes
 
   .. parsed-literal::
 
@@ -26,8 +27,8 @@ Examples
 
 .. code-block:: LAMMPS
 
-   compute 1 all property/chunk count
+   compute 1 all property/chunk bin2d id count
-   compute 1 all property/chunk ID coord1
+   compute 1 all property/chunk myChunks id coord1
 
 Description
 """""""""""
@@ -35,29 +36,28 @@ Description
 Define a computation that stores the specified attributes of chunks of
 atoms.
 
-In LAMMPS, chunks are collections of atoms defined by a
+In LAMMPS, chunks are collections of atoms defined by a :doc:`compute
-:doc:`compute chunk/atom <compute_chunk_atom>` command, which assigns each atom
+chunk/atom <compute_chunk_atom>` command, which assigns each atom to a
-to a single chunk (or no chunk).  The ID for this command is specified
+single chunk (or no chunk).  The ID for this command is specified as
-as chunkID.  For example, a single chunk could be the atoms in a molecule or
+chunkID.  For example, a single chunk could be the atoms in a molecule
-atoms in a spatial bin.  See the :doc:`compute chunk/atom <compute_chunk_atom>`
+or atoms in a spatial bin.  See the :doc:`compute chunk/atom
-and :doc:`Howto chunk <Howto_chunk>` doc pages for details of how chunks can be
+<compute_chunk_atom>` and :doc:`Howto chunk <Howto_chunk>` doc pages
-defined and examples of how they can be used to measure properties of a system.
+for details of how chunks can be defined and examples of how they can
+be used to measure properties of a system.
 
 This compute calculates and stores the specified attributes of chunks
-as global data so they can be accessed by other
+as global data so they can be accessed by other :doc:`output commands
-:doc:`output commands <Howto_output>` and used in conjunction with other
+<Howto_output>` and used in conjunction with other commands that
-commands that generate per-chunk data, such as
+generate per-chunk data, such as :doc:`compute com/chunk
-:doc:`compute com/chunk <compute_com_chunk>` or
+<compute_com_chunk>` or :doc:`compute msd/chunk <compute_msd_chunk>`.
-:doc:`compute msd/chunk <compute_msd_chunk>`.
 
 Note that only atoms in the specified group contribute to the
-calculation of the *count* attribute.  The
+calculation of the *count* attribute.  The :doc:`compute chunk/atom
-:doc:`compute chunk/atom <compute_chunk_atom>` command defines its own group;
+<compute_chunk_atom>` command defines its own group; atoms will have a
-atoms will have a chunk ID = 0 if they are not in that group,
+chunk ID = 0 if they are not in that group, signifying they are not
-signifying they are not assigned to a chunk, and will thus also not
+assigned to a chunk, and will thus also not contribute to this
-contribute to this calculation.  You can specify the "all" group for
+calculation.  You can specify the "all" group for this command if you
-this command if you simply want to include atoms with non-zero chunk
+simply want to include atoms with non-zero chunk IDs.
-IDs.
 
 The *count* attribute is the number of atoms in the chunk.
 
@@ -66,21 +66,24 @@ can only be used if the *compress* keyword was set to *yes* for the
 :doc:`compute chunk/atom <compute_chunk_atom>` command referenced by
 chunkID.  This means that the original chunk IDs (e.g., molecule IDs)
 will have been compressed to remove chunk IDs with no atoms assigned
-to them.  Thus a compressed chunk ID of 3 may correspond to an original
+to them.  Thus a compressed chunk ID of 3 may correspond to an
-chunk ID (molecule ID in this case) of 415.  The *id* attribute will
+original chunk ID (molecule ID in this case) of 415.  The *id*
-then be 415 for the third chunk.
+attribute will then be 415 for the third chunk.
 
 The *coordN* attributes can only be used if a *binning* style was used
-in the :doc:`compute chunk/atom <compute_chunk_atom>` command referenced
-by chunkID.  For *bin/1d*, *bin/2d*, and *bin/3d* styles the attribute
-is the center point of the bin in the corresponding dimension.  Style
-*bin/1d* only defines a *coord1* attribute.  Style *bin/2d* adds a
-*coord2* attribute.  Style *bin/3d* adds a *coord3* attribute.
 
-Note that if the value of the *units* keyword used in the :doc:`compute chunk/atom command <compute_chunk_atom>` is *box* or *lattice*, the
+in the :doc:`compute chunk/atom <compute_chunk_atom>` command
-*coordN* attributes will be in distance :doc:`units <units>`.  If the
+referenced by chunkID.  For *bin/1d*, *bin/2d*, and *bin/3d* styles
-value of the *units* keyword is *reduced*, the *coordN* attributes
+the attribute is the center point of the bin in the corresponding
-will be in unitless reduced units (0--1).
+dimension.  Style *bin/1d* only defines a *coord1* attribute.  Style
+*bin/2d* adds a *coord2* attribute.  Style *bin/3d* adds a *coord3*
+attribute.
+
+Note that if the value of the *units* keyword used in the
+:doc:`compute chunk/atom command <compute_chunk_atom>` is *box* or
+*lattice*, the *coordN* attributes will be in distance :doc:`units
+<units>`.  If the value of the *units* keyword is *reduced*, the
+*coordN* attributes will be in unitless reduced units (0-1).
 
 The simplest way to output the results of the compute property/chunk
 calculation to a file is to use the :doc:`fix ave/time <fix_ave_time>`

doc/src/compute_property_grid.rst

@@ -0,0 +1,114 @@
+.. index:: compute property/grid
+
+compute property/grid command
+=============================
+
+Syntax
+""""""
+
+.. parsed-literal::
+
+   compute ID group-ID property/grid Nx Ny Nz input1 input2 ...
+
+* ID, group-ID are documented in :doc:`compute <compute>` command
+* property/grid = style name of this compute command
+* Nx, Ny, Nz = grid size in each dimension
+* input1,etc = one or more attributes
+
+  .. parsed-literal::
+
+       attributes = id, ix, iy, iz, x, y, z, xs, ys, zs, xc, yc, zc, xsc, ysc, zsc
+         id = ID of grid cell, x fastest, y next, z slowest
+         ix,iy,iz = grid indices in each dimension (1 to N inclusive)
+         x,y,z = coords of lower left corner of grid cell
+         xs,ys,zs = scaled coords of lower left corner of grid cell (0.0 to 1.0)
+         xc,yc,zc = coords of center point of grid cell
+         xsc,ysc,zsc = scaled coords of center point of grid cell (0.0 to 1.0)
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+   compute 1 all property/grid id ix iy iz
+   compute 1 all property/grid id xc yc zc
+
+Description
+"""""""""""
+
+Define a computation that stores the specified attributes of a
+distributed grid.  In LAMMPS, distributed grids are regular 2d or 3d
+grids which overlay a 2d or 3d simulation domain.  Each processor owns
+the grid cells whose center points lie within its sub-domain.  See the
+:doc:`Howto grid <Howto_grid>` doc page for details of how distributed
+grids can be defined by various commands and referenced.
+
+This compute stores the specified attributes of grids as per-grid data
+so they can be accessed by other :doc:`output commands <Howto_output>`
+such as :doc:`dump grid <dump>`.
+
+*Nx*, *Ny*, and *Nz* define the size of the grid.  For a 2d simulation
+*Nz* must be 1.  When this compute is used by :doc:`dump grid <dump>`,
+to output per-grid values from other computes of fixes, the grid size
+specified for this command must be consistent with the grid sizes
+used by the other commands.
+
+The *id* attribute stores the grid ID for each grid cell.  For a
+global grid of size Nx by Ny by Nz (in 3d simulations) the grid IDs
+range from 1 to Nx*Ny*Nz.  They are ordered with the X index of the 3d
+grid varying fastest, then Y, then Z slowest.  For 2d grids (in 2d
+simulations), the grid IDs range from 1 to Nx*Ny, with X varying
+fastest and Y slowest.
+
+The *ix*, *iy*, *iz* attributes are the indices of a grid cell in
+each dimension.  They range from 1 to Nx inclusive in the X dimension,
+and similar for Y and Z.
+
+The *x*, *y*, *z* attributes are the coordinates of the lower left
+corner point of each grid cell.
+
+The *xs*, *ys*, *zs* attributes are also coordinates of the lower left
+corner point of each grid cell, except in scaled coordinates, where
+the lower-left corner of the entire simulation box is (0,0,0) and the
+upper right corner is (1,1,1).
+
+The *xc*, *yc*, *zc* attributes are the coordinates of the center
+point of each grid cell.
+
+The *xsc*, *ysc*, *zsc* attributes are also coordinates of the center
+point each grid cell, except in scaled coordinates, where the
+lower-left corner of the entire simulation box is (0,0,0) and the upper
+right corner is (1,1,1).
+
+For :doc:`triclinic simulation boxes <Howto_triclinic>`, the grid
+point coordinates for (x,y,z) and (xc,yc,zc) will reflect the
+triclinic geometry.  For (xs,yz,zs) and (xsc,ysc,zsc), the coordinates
+are the same for orthogonal versus triclinic boxes.
+
+Output info
+"""""""""""
+
+This compute calculates a per-grid vector or array depending on the
+number of input values.  The length of the vector or number of array
+rows (distributed across all processors) is Nx * Ny * Nz.  For access
+by other commands, the name of the single grid produced by this
+command is "grid".  The name of its per-grid data is "data".
+
+The (x,y,z) and (xc,yc,zc) coordinates are in distance :doc:`units
+<units>`.
+
+Restrictions
+""""""""""""
+
+For 2d simulations, the attributes which refer to
+the Z dimension cannot be used.
+
+Related commands
+""""""""""""""""
+
+:doc:`dump grid <dump>`
+
+Default
+"""""""
+
+none

doc/src/compute_property_local.rst

@@ -85,10 +85,11 @@ Description
 """""""""""
 
 Define a computation that stores the specified attributes as local
-data so it can be accessed by other :doc:`output commands <Howto_output>`.  If the input attributes refer to bond
+data so it can be accessed by other :doc:`output commands
-information, then the number of datums generated, aggregated across
+<Howto_output>`.  If the input attributes refer to bond information,
-all processors, equals the number of bonds in the system.  Ditto for
+then the number of datums generated, aggregated across all processors,
-pairs, angles, etc.
+equals the number of bonds in the system.  Ditto for pairs, angles,
+etc.
 
 If multiple attributes are specified then they must all generate the
 same amount of information, so that the resulting local array has the
@@ -129,17 +130,20 @@ specified compute group.  Likewise for angles, dihedrals, etc.
 For bonds and angles, a bonds/angles that have been broken by setting
 their bond/angle type to 0 will not be included.  Bonds/angles that
 have been turned off (see the :doc:`fix shake <fix_shake>` or
-:doc:`delete_bonds <delete_bonds>` commands) by setting their bond/angle
+:doc:`delete_bonds <delete_bonds>` commands) by setting their
-type negative are written into the file.  This is consistent with the
+bond/angle type negative are written into the file.  This is
-:doc:`compute bond/local <compute_bond_local>` and :doc:`compute angle/local <compute_angle_local>` commands
+consistent with the :doc:`compute bond/local <compute_bond_local>` and
+:doc:`compute angle/local <compute_angle_local>` commands
 
 Note that as atoms migrate from processor to processor, there will be
 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, output from the :doc:`compute bond/local <compute_bond_local>` command can be combined with bond
+For example, output from the :doc:`compute bond/local
-atom indices from this command and output by the :doc:`dump local <dump>` command in a consistent way.
+<compute_bond_local>` command can be combined with bond atom indices
+from this command and output by the :doc:`dump local <dump>` command
+in a consistent way.
 
 The *natom1* and *natom2* or *patom1* and *patom2* attributes refer
 to the atom IDs of the 2 atoms in each pairwise interaction computed
@@ -177,9 +181,8 @@ the array is the number of bonds, angles, etc.  If a single input is
 specified, a local vector is produced.  If two or more inputs are
 specified, a local array is produced where the number of columns = the
 number of inputs.  The vector or array can be accessed by any command
-that uses local values from a compute as input.  See the
+that uses local values from a compute as input.  See the :doc:`Howto
-:doc:`Howto output <Howto_output>` page for an overview of LAMMPS output
+output <Howto_output>` page for an overview of LAMMPS output options.
-options.
 
 The vector or array values will be integers that correspond to the
 specified attribute.

doc/src/compute_temp.rst

@@ -29,8 +29,9 @@ Description
 
 Define a computation that calculates the temperature of a group of
 atoms.  A compute of this style can be used by any command that
-computes a temperature (e.g., :doc:`thermo_modify <thermo_modify>`,
+computes a temperature, e.g. :doc:`thermo_modify <thermo_modify>`,
-:doc:`fix temp/rescale <fix_temp_rescale>`, :doc:`fix npt <fix_nh>`)
+:doc:`fix temp/rescale <fix_temp_rescale>`, :doc:`fix npt <fix_nh>`,
+etc.
 
 The temperature is calculated by the formula
 
@@ -39,17 +40,17 @@ The temperature is calculated by the formula
    \text{KE} = \frac{\text{dim}}{2} N k_B T,
 
 where KE = total kinetic energy of the group of atoms (sum of
-:math:`\frac12 m v^2`), dim = 2 or 3 is the dimensionality of the simulation,
+:math:`\frac12 m v^2`), dim = 2 or 3 is the dimensionality of the
-:math:`N` is the number of atoms in the group, :math:`k_B` is the Boltzmann
+simulation, :math:`N` is the number of atoms in the group, :math:`k_B`
-constant, and :math:`T` is the absolute temperature.
+is the Boltzmann constant, and :math:`T` is the absolute temperature.
 
 A kinetic energy tensor, stored as a six-element vector, is also
 calculated by this compute for use in the computation of a pressure
 tensor.  The formula for the components of the tensor is the same as
-the above formula, except that :math:`v^2` is replaced by
+the above formula, except that :math:`v^2` is replaced by :math:`v_x
-:math:`v_x v_y` for the :math:`xy` component, and so on.
+v_y` for the :math:`xy` component, and so on.  The six components of
-The six components of the vector are ordered :math:`xx`, :math:`yy`,
+the vector are ordered :math:`xx`, :math:`yy`, :math:`zz`, :math:`xy`,
-:math:`zz`, :math:`xy`, :math:`xz`, :math:`yz`.
+:math:`xz`, :math:`yz`.
 
 The number of atoms contributing to the temperature is assumed to be
 constant for the duration of the run; use the *dynamic* option of the
@@ -85,11 +86,10 @@ Output info
 """""""""""
 
 This compute calculates a global scalar (the temperature) and a global
-vector of length six (KE tensor), which can be accessed by indices 1--6.
+vector of length six (KE tensor), which can be accessed by indices
-These values can be used by any command that uses global scalar or
+1--6.  These values can be used by any command that uses global scalar
-vector values from a compute as input.  See the
+or vector values from a compute as input.  See the :doc:`Howto output
-:doc:`Howto output <Howto_output>` page for an overview of LAMMPS output
+<Howto_output>` page for an overview of LAMMPS output options.
-options.
 
 The scalar value calculated by this compute is "intensive".  The
 vector values are "extensive".
@@ -104,7 +104,9 @@ Restrictions
 Related commands
 """"""""""""""""
 
-:doc:`compute temp/partial <compute_temp_partial>`, :doc:`compute temp/region <compute_temp_region>`, :doc:`compute pressure <compute_pressure>`
+:doc:`compute temp/partial <compute_temp_partial>`,
+:doc:`compute temp/region <compute_temp_region>`,
+:doc:`compute pressure <compute_pressure>`
 
 Default
 """""""

doc/src/create_box.rst

@@ -66,20 +66,21 @@ positive or negative values and are called "tilt factors" because they
 are the amount of displacement applied to faces of an originally
 orthogonal box to transform it into the parallelepiped.
 
-By default, a *prism* region used with the create_box command must
+By default, a *prism* region used with the create_box command must have
-have tilt factors :math:`(xy,xz,yz)` that do not skew the box more than half
+tilt factors :math:`(xy,xz,yz)` that do not skew the box more than half
 the distance of the parallel box length.  For example, if
 :math:`x_\text{lo} = 2` and :math:`x_\text{hi} = 12`, then the :math:`x`
-box length is 10 and the :math:`xy` tilt factor must be between :math:`-5` and
+box length is 10 and the :math:`xy` tilt factor must be between
-:math:`5`.  Similarly, both :math:`xz` and :math:`yz` must be between
+:math:`-5` and :math:`5`.  Similarly, both :math:`xz` and :math:`yz`
-:math:`-(x_\text{hi}-x_\text{lo})/2` and :math:`+(y_\text{hi}-y_\text{lo})/2`.
+must be between :math:`-(x_\text{hi}-x_\text{lo})/2` and
-Note that this is not a limitation, since if the maximum tilt factor is 5 (as
+:math:`+(y_\text{hi}-y_\text{lo})/2`.  Note that this is not a
-in this example), then configurations with tilt :math:`= \dots, -15`,
+limitation, since if the maximum tilt factor is 5 (as in this example),
-:math:`-5`, :math:`5`, :math:`15`, :math:`25, \dots`
+then configurations with tilt :math:`= \dots, -15`, :math:`-5`,
-are all geometrically equivalent.  If you wish to define a box with tilt
+:math:`5`, :math:`15`, :math:`25, \dots` are all geometrically
-factors that exceed these limits, you can use the :doc:`box tilt <box>`
+equivalent.  Simulations with large tilt factors will run inefficiently,
-command, with a setting of *large*\ ; a setting of *small* is the
+since they require more ghost atoms and thus more communication.  With
-default.
+very large tilt factors, LAMMPS will eventually produce incorrect
+trajectories and stop with errors due to lost atoms or similar.
 
 See the :doc:`Howto triclinic <Howto_triclinic>` page for a
 geometric description of triclinic boxes, as defined by LAMMPS, and

doc/src/delete_atoms.rst

@@ -135,7 +135,7 @@ number of atoms in the system.  Note that this is not done for
 molecular systems (see the :doc:`atom_style <atom_style>` command),
 regardless of the *compress* setting, since it would foul up the bond
 connectivity that has already been assigned.  However, the
-:doc:`reset_atom_ids <reset_atom_ids>` command can be used after this
+:doc:`reset_atoms id <reset_atoms>` command can be used after this
 command to accomplish the same thing.
 
 Note that the re-assignment of IDs is not really a compression, where
@@ -203,7 +203,7 @@ using molecule template files via the :doc:`molecule <molecule>` and
 Related commands
 """"""""""""""""
 
-:doc:`create_atoms <create_atoms>`, :doc:`reset_atom_ids <reset_atom_ids>`
+:doc:`create_atoms <create_atoms>`, :doc:`reset_atoms id <reset_atoms>`
 
 Default
 """""""

doc/src/dihedral_table.rst

@@ -114,6 +114,10 @@ below.
 
 ----------
 
+Suitable tables for use with this dihedral style can be created using
+the Python code in the ``tools/tabulate`` folder of the LAMMPS source
+code distribution.
+
 The format of a tabulated file is as follows (without the
 parenthesized comments).  It can begin with one or more comment
 or blank lines.

doc/src/dump.rst

@@ -3,6 +3,8 @@
 .. index:: dump cfg
 .. index:: dump custom
 .. index:: dump dcd
+.. index:: dump grid
+.. index:: dump grid/vtk
 .. index:: dump local
 .. index:: dump xtc
 .. index:: dump yaml
@@ -57,46 +59,48 @@ Syntax
 
 .. code-block:: LAMMPS
 
-   dump ID group-ID style N file args
+   dump ID group-ID style N file attribute1 attribute2 ...
 
 * ID = user-assigned name for the dump
 * group-ID = ID of the group of atoms to be dumped
-* style = *atom* or *atom/adios* or *atom/gz* or *atom/zstd* or *atom/mpiio* or *cfg* or *cfg/gz* or *cfg/zstd* or *cfg/mpiio* or *cfg/uef* or *custom* or *custom/gz* or *custom/zstd* or *custom/mpiio* or *custom/adios* or *dcd* or *h5md* or *image* or *local* or *local/gz* or *local/zstd* or *molfile* or *movie* or *netcdf* or *netcdf/mpiio* or *vtk* or *xtc* or *xyz* or *xyz/gz* or *xyz/zstd* or *xyz/mpiio* or *yaml*
+* style = *atom* or *atom/adios* or *atom/gz* or *atom/zstd* or *atom/mpiio* or *cfg* or *cfg/gz* or *cfg/zstd* or *cfg/mpiio* or *cfg/uef* or *custom* or *custom/gz* or *custom/zstd* or *custom/mpiio* or *custom/adios* or *dcd* or *grid* or *grid/vtk* or *h5md* or *image* or *local* or *local/gz* or *local/zstd* or *molfile* or *movie* or *netcdf* or *netcdf/mpiio* or *vtk* or *xtc* or *xyz* or *xyz/gz* or *xyz/zstd* or *xyz/mpiio* or *yaml*
 * N = dump on timesteps which are multiples of N
 * file = name of file to write dump info to
-* args = list of arguments for a particular style
+* attribute1,attribute2,... = list of attributes for a particular style
 
   .. parsed-literal::
 
-       *atom* args = none
+       *atom* attributes = none
-       *atom/adios* args = none,  discussed on :doc:`dump atom/adios <dump_adios>` page
+       *atom/adios* attributes = none,  discussed on :doc:`dump atom/adios <dump_adios>` page
-       *atom/gz* args = none
+       *atom/gz* attributes = none
-       *atom/zstd* args = none
+       *atom/zstd* attributes = none
-       *atom/mpiio* args = none
+       *atom/mpiio* attributes = none
-       *cfg* args = same as *custom* args, see below
+       *cfg* attributes = same as *custom* attributes, see below
-       *cfg/gz* args = same as *custom* args, see below
+       *cfg/gz* attributes = same as *custom* attributes, see below
-       *cfg/zstd* args = same as *custom* args, see below
+       *cfg/zstd* attributes = same as *custom* attributes, see below
-       *cfg/mpiio* args = same as *custom* args, see below
+       *cfg/mpiio* attributes = same as *custom* attributes, see below
-       *cfg/uef* args = same as *custom* args, discussed on :doc:`dump cfg/uef <dump_cfg_uef>` page
+       *cfg/uef* attributes = same as *custom* attributes, discussed on :doc:`dump cfg/uef <dump_cfg_uef>` page
-       *custom*, *custom/gz*, *custom/zstd*, *custom/mpiio* args = see below
+       *custom*, *custom/gz*, *custom/zstd*, *custom/mpiio* attributes = see below
-       *custom/adios* args = same as *custom* args, discussed on :doc:`dump custom/adios <dump_adios>` page
+       *custom/adios* attributes = same as *custom* attributes, discussed on :doc:`dump custom/adios <dump_adios>` page
-       *dcd* args = none
+       *dcd* attributes = none
-       *h5md* args = discussed on :doc:`dump h5md <dump_h5md>` page
+       *h5md* attributes = discussed on :doc:`dump h5md <dump_h5md>` page
-       *image* args = discussed on :doc:`dump image <dump_image>` page
+       *grid* attributes = see below
-       *local*, *local/gz*, *local/zstd* args = see below
+       *grid/vtk* attributes = see below
-       *molfile* args = discussed on :doc:`dump molfile <dump_molfile>` page
+       *image* attributes = discussed on :doc:`dump image <dump_image>` page
-       *movie* args = discussed on :doc:`dump image <dump_image>` page
+       *local*, *local/gz*, *local/zstd* attributes = see below
-       *netcdf* args = discussed on :doc:`dump netcdf <dump_netcdf>` page
+       *molfile* attributes = discussed on :doc:`dump molfile <dump_molfile>` page
-       *netcdf/mpiio* args = discussed on :doc:`dump netcdf <dump_netcdf>` page
+       *movie* attributes = discussed on :doc:`dump image <dump_image>` page
-       *vtk* args = same as *custom* args, see below, also :doc:`dump vtk <dump_vtk>` page
+       *netcdf* attributes = discussed on :doc:`dump netcdf <dump_netcdf>` page
-       *xtc* args = none
+       *netcdf/mpiio* attributes = discussed on :doc:`dump netcdf <dump_netcdf>` page
-       *xyz* args = none
+       *vtk* attributes = same as *custom* attributes, see below, also :doc:`dump vtk <dump_vtk>` page
-       *xyz/gz* args = none
+       *xtc* attributes = none
-       *xyz/zstd* args = none
+       *xyz* attributes = none
-       *xyz/mpiio* args = none
+       *xyz/gz* attributes = none
-       *yaml* args = same as *custom* args, see below
+       *xyz/zstd* attributes = none
+       *xyz/mpiio* attributes = none
+       *yaml* attributes = same as *custom* attributes, see below
 
-* *custom* or *custom/gz* or *custom/zstd* or *custom/mpiio* or *cfg* or *cfg/gz* or *cfg/zstd* or *cfg/mpiio* or *cfg/uef* or *netcdf* or *netcdf/mpiio* or *yaml* args = list of atom attributes
+* *custom* or *custom/gz* or *custom/zstd* or *custom/mpiio* or *cfg* or *cfg/gz* or *cfg/zstd* or *cfg/mpiio* or *cfg/uef* or *netcdf* or *netcdf/mpiio* or *yaml* attributes:
 
   .. parsed-literal::
 
@@ -143,7 +147,7 @@ Syntax
            i2_name[I] = Ith column of custom integer array with name, I can include wildcard (see below)
            d2_name[I] = Ith column of custom floating point vector with name, I can include wildcard (see below)
 
-* *local* or *local/gz* or *local/zstd* args = list of local attributes
+* *local* or *local/gz* or *local/zstd* attributes:
 
   .. parsed-literal::
 
@@ -154,6 +158,18 @@ Syntax
            f_ID = local vector calculated by a fix with ID
            f_ID[I] = Ith column of local array calculated by a fix with ID, I can include wildcard (see below)
 
+* *grid* or *grid/vtk* attributes:
+
+  .. parsed-literal::
+
+         possible attributes = c_ID:gname:dname, c_ID:gname:dname[I], f_ID:gname:dname, f_ID:gname:dname[I]
+           gname = name of grid defined by compute or fix
+           dname = name of data field defined by compute or fix
+           c_ID = per-grid vector calculated by a compute with ID
+           c_ID[I] = Ith column of per-grid array calculated by a compute with ID, I can include wildcard (see below)
+           f_ID = per-grid vector calculated by a fix with ID
+           f_ID[I] = Ith column of per-grid array calculated by a fix with ID, I can include wildcard (see below)
+
 Examples
 """"""""
 
@@ -176,24 +192,32 @@ Examples
 Description
 """""""""""
 
-Dump a snapshot of atom quantities to one or more files once every
+Dump a snapshot of quantities to one or more files once every
-:math:`N` timesteps in one of several styles.  The *image* and *movie*
+:math:`N` timesteps in one of several styles.  The timesteps on which
-styles are the exception: the *image* style renders a JPG, PNG, or PPM
+dump output is written can also be controlled by a variable.  See the
-image file of the atom configuration every :math:`N` timesteps while
+:doc:`dump_modify every <dump_modify>` command.
-the *movie* style combines and compresses them into a movie file; both
+
-are discussed in detail on the :doc:`dump image <dump_image>` page.
+Almost all the styles output per-atom data, i.e. one or more values
-The timesteps on which dump output is written can also be controlled
+per atom.  The exceptions are as follows.  The *local* styles output
-by a variable.  See the :doc:`dump_modify every <dump_modify>`
+one or more values per bond (angle, dihedral, improper) or per pair of
-command.
+interacting atoms (force or neighbor interactions).  The *grid* styles
+output one or more values per grid cell, which are produced by other
+commands which overlay the simulation domain with a regular grid.  See
+the :doc:`Howto grid <Howto_grid>` doc page for details.  The *image*
+style renders a JPG, PNG, or PPM image file of the system for each
+snapshot, while the *movie* style combines and compresses the series
+of images into a movie file; both styles are discussed in detail on
+the :doc:`dump image <dump_image>` page.
 
 Only information for atoms in the specified group is dumped.  The
-:doc:`dump_modify thresh and region and refresh <dump_modify>` commands
+:doc:`dump_modify thresh and region and refresh <dump_modify>`
-can also alter what atoms are included.  Not all styles support
+commands can also alter what atoms are included.  Not all styles
-these options; see details on the :doc:`dump_modify <dump_modify>` doc page.
+support these options; see details on the :doc:`dump_modify
+<dump_modify>` doc page.
 
-As described below, the filename determines the kind of output (text
+As described below, the filename determines the kind of output: text
-or binary or gzipped, one big file or one per timestep, one big file
+or binary or gzipped, one big file or one per timestep, one file for
-or multiple smaller files).
+all the processors or multiple smaller files.
 
 .. note::
 
@@ -202,79 +226,66 @@ or multiple smaller files).
    to a dump file may be slightly outside the simulation box.
    Re-neighbor timesteps will not typically coincide with the
    timesteps dump snapshots are written.  See the :doc:`dump_modify
-   pbc <dump_modify>` command if you with to force coordinates to be
+   pbc <dump_modify>` command if you wish to force coordinates to be
    strictly inside the simulation box.
 
 .. note::
 
-   Unless the :doc:`dump_modify sort <dump_modify>` option is
+   Unless the :doc:`dump_modify sort <dump_modify>` option is invoked,
-   invoked, the lines of atom information written to dump files
+   the lines of atom or grid information written to dump files
-   (typically one line per atom) will be in an indeterminate order for
+   (typically one line per atom or grid cell) will be in an
-   each snapshot.  This is even true when running on a single processor,
+   indeterminate order for each snapshot.  This is even true when
-   if the :doc:`atom_modify sort <atom_modify>` option is on, which it is
+   running on a single processor, if the :doc:`atom_modify sort
-   by default.  In this case atoms are re-ordered periodically during a
+   <atom_modify>` option is on, which it is by default.  In this case
-   simulation, due to spatial sorting.  It is also true when running in
+   atoms are re-ordered periodically during a simulation, due to
-   parallel, because data for a single snapshot is collected from
+   spatial sorting.  It is also true when running in parallel, because
-   multiple processors, each of which owns a subset of the atoms.
+   data for a single snapshot is collected from multiple processors,
+   each of which owns a subset of the atoms.
 
-For the *atom*, *custom*, *cfg*, and *local* styles, sorting is off by
+For the *atom*, *custom*, *cfg*, *grid*, and *local* styles, sorting
-default.  For the *dcd*, *xtc*, *xyz*, and *molfile* styles, sorting
+is off by default.  For the *dcd*, *grid/vtk*, *xtc*, *xyz*, and
-by atom ID is on by default. See the :doc:`dump_modify <dump_modify>`
+*molfile* styles, sorting by atom ID or grid ID is on by default. See
-page for details.
+the :doc:`dump_modify <dump_modify>` page for details.
 
-The *atom/gz*, *cfg/gz*, *custom/gz*, *local/gz*, and *xyz/gz* styles
+The *style* keyword determines what kind of data is written to the
-are identical in command syntax to the corresponding styles without
+dump file(s) and in what format.
-"gz", however, they generate compressed files using the zlib
-library. Thus the filename suffix ".gz" is mandatory. This is an
-alternative approach to writing compressed files via a pipe, as done by
-the regular dump styles, which may be required on clusters where the
-interface to the high-speed network disallows using the fork() library
-call (which is needed for a pipe).  For the remainder of this page, you
-should thus consider the *atom* and *atom/gz* styles (etc.) to be
-inter-changeable, with the exception of the required filename suffix.
 
-Similarly, the *atom/zstd*, *cfg/zstd*, *custom/zstd*, *local/zstd*, and
+Note that *atom*, *custom*, *dcd*, *xtc*, *xyz*, and *yaml* style dump
-*xyz/zstd* styles are identical to the gz styles, but use the Zstd
+files can be read directly by `VMD <https://www.ks.uiuc.edu/Research/vmd>`_,
-compression library instead and require the ".zst" suffix. See the
+a popular tool for visualizing and analyzing trajectories from atomic
-:doc:`dump_modify <dump_modify>` page for details on how to control the
+and molecular systems.  For reading *netcdf* style dump files, the
-compression level in both variants.
+netcdf plugin needs to be recompiled from source using a NetCDF version
+compatible with the one used by LAMMPS.  The bundled plugin binary
+uses a very old version of NetCDF that is not compatible with LAMMPS.
 
-As explained below, the *atom/mpiio*, *cfg/mpiio*, *custom/mpiio*, and
+Likewise the `OVITO visualization package <https://www.ovito.org>`_,
-*xyz/mpiio* styles are identical in command syntax and in the format of
+popular for materials modeling, can read the *atom*, *custom*,
-the dump files they create, to the corresponding styles without "mpiio",
+*local*, *xtc*, *cfg*, *netcdf*, and *xyz* style atom dump files
-except the single dump file they produce is written in parallel via the
+directly.  With version 3.8 and above, OVITO can also read and
-MPI-IO library.  For the remainder of this page, you should thus
+visualize *grid* style dump files with grid cell data, including
-consider the *atom* and *atom/mpiio* styles (etc.) to be
+iso-surface images of the grid cell values.
-inter-changeable.  The one exception is how the filename is specified
-for the MPI-IO styles, as explained below.
 
-.. warning::
+Note that settings made via the :doc:`dump_modify <dump_modify>`
-
+command can also alter the format of individual values and content of
-   The MPIIO package is currently unmaintained and has become
+the dump file itself.  This includes the precision of values output to
-   unreliable. Use with caution.
+text-based dump files which is controlled by the :doc:`dump_modify
-
+format <dump_modify>` command and its options.
-The precision of values output to text-based dump files can be
-controlled by the :doc:`dump_modify format <dump_modify>` command and
-its options.
 
 ----------
 
-The *style* keyword determines what atom quantities are written to the
+Format of native LAMMPS format dump files:
-file and in what format.  Settings made via the
-:doc:`dump_modify <dump_modify>` command can also alter the format of
-individual values and the file itself.
 
-The *atom*, *local*, and *custom* styles create files in a simple text
+The *atom*, *custom*, *grid*, and *local* styles create files in a
-format that is self-explanatory when viewing a dump file.  Some of the
+simple LAMMPS-specific text format that is self-explanatory when
-LAMMPS post-processing tools described on the :doc:`Tools <Tools>` doc
+viewing a dump file.  Many post-processing tools either included with
-page, including `Pizza.py <https://lammps.github.io/pizza>`_,
+LAMMPS or third-party tools can read this format, as does the
-work with this format, as does the :doc:`rerun <rerun>` command.
+:doc:`rerun <rerun>` command.  See tools described on the :doc:`Tools
+<Tools>` doc page for examples, including `Pizza.py
+<https://lammps.github.io/pizza>`_.
 
-For post-processing purposes the *atom*, *local*, and *custom* text
+For all these styles, the dimensions of the simulation box are
-files are self-describing in the following sense.
+included in each snapshot.  For an orthogonal simulation box this
-
+information is formatted as:
-The dimensions of the simulation box are included in each snapshot.
-For an orthogonal simulation box this information is formatted as:
 
 .. parsed-literal::
 
@@ -316,10 +327,13 @@ bounding box extents (xlo_bound, xhi_bound, etc.) are calculated from the
 triclinic parameters, and how to transform those parameters to and
 from other commonly used triclinic representations.
 
-The "ITEM: ATOMS" line in each snapshot lists column descriptors for
+The *atom* and *custom* styles output a "ITEM: NUMBER OF ATOMS" line
-the per-atom lines that follow.  For example, the descriptors would be
+with the count of atoms in the snapshot.  Likewise they output an
-"id type xs ys zs" for the default *atom* style, and would be the atom
+"ITEM: ATOMS" line which includes column descriptors for the per-atom
-attributes you specify in the dump command for the *custom* style.
+lines that follow.  For example, the descriptors would be "id type xs
+ys zs" for the default *atom* style, and would be the atom attributes
+you specify in the dump command for the *custom* style.  Each
+subsequent line will list the data for a single atom.
 
 For style *atom*, atom coordinates are written to the file, along with
 the atom ID and atom type.  By default, atom coords are written in a
@@ -332,12 +346,31 @@ added for each atom via dump_modify.
 Style *custom* allows you to specify a list of atom attributes to be
 written to the dump file for each atom.  Possible attributes are
 listed above and will appear in the order specified.  You cannot
-specify a quantity that is not defined for a particular simulation---such as
+specify a quantity that is not defined for a particular
-*q* for atom style *bond*, since that atom style does not
+simulation---such as *q* for atom style *bond*, since that atom style
-assign charges.  Dumps occur at the very end of a timestep, so atom
+does not assign charges.  Dumps occur at the very end of a timestep,
-attributes will include effects due to fixes that are applied during
+so atom attributes will include effects due to fixes that are applied
-the timestep.  An explanation of the possible dump custom attributes
+during the timestep.  An explanation of the possible dump custom
-is given below.
+attributes is given below.
+
+.. versionadded:: 22Dec2022
+
+For style *grid* the extent of the Nx by Ny by Nz grid that overlays
+the simulation domain is output with each snapshot:
+
+.. parsed-literal::
+
+   ITEM: GRID EXTENT
+   nx ny nz
+
+For 2d simulations, nz will be 1.  There will also be an "ITEM: GRID
+DATA" line which includes column descriptors for the per grid cell
+data.  Each subsequent line (Nx * Ny * Nz lines) will list the data
+for a single grid cell.  If grid cell IDs are included in the output
+via the :doc:`compute property/grid <compute_property_grid>` command,
+then the IDs will range from 1 to N = Nx*Ny*Nz.  The ordering of IDs
+is with the x index varying fastest, then the y index, and the z index
+varying slowest.
 
 For style *local*, local output generated by :doc:`computes <compute>`
 and :doc:`fixes <fix>` is used to generate lines of output that is
@@ -351,6 +384,17 @@ generate information on bonds, angles, etc. that can be cut and pasted
 directly into a data file read by the :doc:`read_data <read_data>`
 command.
 
+----------
+
+Dump files in other popular formats:
+
+
+.. note::
+
+   This section only discusses file formats relevant to this doc page.
+   The top of this page has links to other dump commands (with their
+   own pages) which write files in additional popular formats.
+
 Style *cfg* has the same command syntax as style *custom* and writes
 extended CFG format files, as used by the `AtomEye
 <http://li.mit.edu/Archive/Graphics/A/>`_ visualization package.
@@ -387,15 +431,15 @@ periodic box.  Note that these coordinates may thus be far outside
 the box size stored with the snapshot.
 
 The *xtc* style writes XTC files, a compressed trajectory format used
-by the GROMACS molecular dynamics package, and described
+by the GROMACS molecular dynamics package, and described `here
-`here <https://manual.gromacs.org/current/reference-manual/file-formats.html#xtc>`_.
+<https://manual.gromacs.org/current/reference-manual/file-formats.html#xtc>`_.
 The precision used in XTC files can be adjusted via the
 :doc:`dump_modify <dump_modify>` command.  The default value of 1000
 means that coordinates are stored to 1/1000 nanometer accuracy.  XTC
-files are portable binary files written in the NFS XDR data format,
+files are portable binary files written in the NFS XDR data format, so
-so that any machine which supports XDR should be able to read them.
+that any machine which supports XDR should be able to read them.  The
-The number of atoms per snapshot cannot change with the *xtc* style.
+number of atoms per snapshot cannot change with the *xtc* style.  The
-The *unwrap* option of the :doc:`dump_modify <dump_modify>` command allows
+*unwrap* option of the :doc:`dump_modify <dump_modify>` command allows
 XTC coordinates to be written "unwrapped" by the image flags for each
 atom.  Unwrapped means that if the atom has passed through a periodic
 boundary one or more times, the value is printed for what the
@@ -404,27 +448,41 @@ box.  Note that these coordinates may thus be far outside the box size
 stored with the snapshot.
 
 The *xyz* style writes XYZ files, which is a simple text-based
-coordinate format that many codes can read. Specifically it has
+coordinate format that many codes can read. Specifically it has a line
-a line with the number of atoms, then a comment line that is
+with the number of atoms, then a comment line that is usually ignored
-usually ignored followed by one line per atom with the atom type
+followed by one line per atom with the atom type and the :math:`x`-,
-and the :math:`x`-, :math:`y`-, and :math:`z`-coordinate of that atom.
+:math:`y`-, and :math:`z`-coordinate of that atom.  You can use the
-You can use the :doc:`dump_modify element <dump_modify>` option to change the
+:doc:`dump_modify element <dump_modify>` option to change the output
-output from using the (numerical) atom type to an element name (or some other
+from using the (numerical) atom type to an element name (or some other
-label). This will help many visualization programs to guess bonds and colors.
+label). This will help many visualization programs to guess bonds and
+colors.
+
+.. versionadded:: 22Dec2022
+
+The *grid/vtk* style writes VTK files for grid data on a regular
+rectilinear grid.  Its content is conceptually similar to that of the
+text file produced by the *grid* style, except that it in an XML-based
+format which visualization programs which support the VTK format can
+read, e.g. the `ParaView tool <https://www.paraview.org>`_.  For this
+style, there can only be 1 or 3 per grid cell attributes specified.
+If it is a single value, it is a scalar quantity.  If 3 values are
+specified it is encoded in the VTK file as a vector quantity (for each
+grid cell).  The filename for this style must include a "\*" wildcard
+character to produce one file per snapshot; see details below.
 
 .. versionadded:: 4May2022
 
 Dump style *yaml* has the same command syntax as style *custom* and
-writes YAML format files that can be easily parsed by a variety of data
+writes YAML format files that can be easily parsed by a variety of
-processing tools and programming languages.  Each timestep will be
+data processing tools and programming languages.  Each timestep will
-written as a YAML "document" (i.e., starts with "---" and ends with
+be written as a YAML "document" (i.e., starts with "---" and ends with
 "...").  The style supports writing one file per timestep through the
-"\*" wildcard but not multi-processor outputs with the "%" token in the
+"\*" wildcard but not multi-processor outputs with the "%" token in
-filename.  In addition to per-atom data, :doc:`thermo <thermo>` data can
+the filename.  In addition to per-atom data, :doc:`thermo <thermo>`
-be included in the *yaml* style dump file using the :doc:`dump_modify
+data can be included in the *yaml* style dump file using the
-thermo yes <dump_modify>`. The data included in the dump file uses the
+:doc:`dump_modify thermo yes <dump_modify>`. The data included in the
-"thermo" tag and is otherwise identical to data specified by the
+dump file uses the "thermo" tag and is otherwise identical to data
-:doc:`thermo_style <thermo_style>` command.
+specified by the :doc:`thermo_style <thermo_style>` command.
 
 Below is an example for a YAML format dump created by the following commands.
 
@@ -435,13 +493,13 @@ Below is an example for a YAML format dump created by the following commands.
 
 The tags "time", "units", and "thermo" are optional and enabled by the
 dump_modify command. The list under the "box" tag has three lines for
-orthogonal boxes and four lines for triclinic boxes, where the first three are
+orthogonal boxes and four lines for triclinic boxes, where the first
-the box boundaries and the fourth the three tilt factors (:math:`xy`,
+three are the box boundaries and the fourth the three tilt factors
-:math:`xz`, :math:`yz`).  The "thermo" data follows the format of the *yaml*
+(:math:`xy`, :math:`xz`, :math:`yz`).  The "thermo" data follows the
-thermo style.  The "keywords" tag lists the per-atom properties contained in
+format of the *yaml* thermo style.  The "keywords" tag lists the
-the "data" columns, which contain a list with one line per atom.  The keywords
+per-atom properties contained in the "data" columns, which contain a
-may be renamed using the dump_modify command same as for the *custom* dump
+list with one line per atom.  The keywords may be renamed using the
-style.
+dump_modify command same as for the *custom* dump style.
 
 .. code-block:: yaml
 
@@ -479,11 +537,7 @@ style.
 
 ----------
 
-Note that *atom*, *custom*, *dcd*, *xtc*, and *xyz* style dump files
+Frequency of dump output:
-can be read directly by `VMD <https://www.ks.uiuc.edu/Research/vmd>`_, a
-popular molecular viewing program.
-
-----------
 
 Dumps are performed on timesteps that are a multiple of :math:`N`
 (including timestep 0) and on the last timestep of a minimization if
@@ -508,29 +562,35 @@ every/time <dump_modify>` command can be used.  This can be useful
 when the timestep size varies during a simulation run, e.g. by use of
 the :doc:`fix dt/reset <fix_dt_reset>` command.
 
-The specified filename determines how the dump file(s) is written.
+----------
-The default is to write one large text file, which is opened when the
-dump command is invoked and closed when an :doc:`undump <undump>`
-command is used or when LAMMPS exits.  For the *dcd* and *xtc* styles,
-this is a single large binary file.
 
-Dump filenames can contain two wildcard characters.  If a "\*"
+Dump filenames:
-character appears in the filename, then one file per snapshot is
+
-written and the "\*" character is replaced with the timestep value.
+The specified dump filename determines how the dump file(s) is
-For example, tmp.dump.\* becomes tmp.dump.0, tmp.dump.10000,
+written.  The default is to write one large text file, which is opened
-tmp.dump.20000, etc.  This option is not available for the *dcd* and
+when the dump command is invoked and closed when an :doc:`undump
-*xtc* styles.  Note that the :doc:`dump_modify pad <dump_modify>`
+<undump>` command is used or when LAMMPS exits.  For the *dcd* and
-command can be used to insure all timestep numbers are the same length
+*xtc* styles, this is a single large binary file.
-(e.g., 00010), which can make it easier to read a series of dump files
+
-in order with some post-processing tools.
+Many of the styles allow dump filenames to contain either or both of
+two wildcard characters.  If a "\*" character appears in the filename,
+then one file per snapshot is written and the "\*" character is
+replaced with the timestep value.  For example, tmp.dump.\* becomes
+tmp.dump.0, tmp.dump.10000, tmp.dump.20000, etc.  This option is not
+available for the *dcd* and *xtc* styles.  Note that the
+:doc:`dump_modify pad <dump_modify>` command can be used to insure all
+timestep numbers are the same length (e.g., 00010), which can make it
+easier to read a series of dump files in order with some
+post-processing tools.
 
 If a "%" character appears in the filename, then each of P processors
 writes a portion of the dump file, and the "%" character is replaced
-with the processor ID from :math:`0` to :math:`P-1`.  For example, tmp.dump.%
+with the processor ID from :math:`0` to :math:`P-1`.  For example,
-becomes tmp.dump.0, tmp.dump.1, ... tmp.dump.:math:`P-1`, etc.  This creates
+tmp.dump.% becomes tmp.dump.0, tmp.dump.1, ... tmp.dump.:math:`P-1`,
-smaller files and can be a fast mode of output on parallel machines that
+etc.  This creates smaller files and can be a fast mode of output on
-support parallel I/O for output. This option is **not** available for the
+parallel machines that support parallel I/O for output. This option is
-*dcd*, *xtc*, *xyz*, and *yaml* styles.
+**not** available for the *dcd*, *xtc*, *xyz*, *grid/vtk*, and *yaml*
+styles.
 
 By default, :math:`P` is the the number of processors, meaning one file per
 processor, but :math:`P` can be set to a smaller value via the *nfile* or
@@ -541,47 +601,41 @@ when running on large numbers of processors.
 Note that using the "\*" and "%" characters together can produce a
 large number of small dump files!
 
-For the *atom/mpiio*, *cfg/mpiio*, *custom/mpiio*, and *xyz/mpiio*
+For styles that end with *mpiio* an ".mpiio" must appear somewhere in
-styles, a single dump file is written in parallel via the MPI-IO
+the specified filename.  These styles write their dump file in
-library, which is part of the MPI standard for versions 2.0 and above.
+parallel via the MPI-IO library, which is part of the MPI standard for
-Using MPI-IO requires two steps.  First, build LAMMPS with its MPIIO
+versions 2.0 and above.  Note these styles are identical in command
-package installed, viz.,
+syntax to the corresponding styles without "mpiio".  Likewise, the
-
+dump files produced by these MPI-IO styles are identical in format to
-.. code-block:: bash
+the files produced by their non-MPI-IO style counterparts.  This means
-
+you can write a dump file using MPI-IO and use the :doc:`read_dump
-   make yes-mpiio    # installs the MPIIO package
-   make mpi          # build LAMMPS for your platform
-
-Second, use a dump filename which contains ".mpiio".  Note that it does
-not have to end in ".mpiio", just contain those characters.  Unlike
-MPI-IO restart files, which must be both written and read using MPI-IO,
-the dump files produced by these MPI-IO styles are identical in format
-to the files produced by their non-MPI-IO style counterparts.  This
-means you can write a dump file using MPI-IO and use the :doc:`read_dump
 <read_dump>` command or perform other post-processing, just as if the
 dump file was not written using MPI-IO.
 
+Because MPI-IO dump files are one large file which all processors
+write to, you cannot use the "%" wildcard character described above in
+the filename.  However you can use the ".bin" or ".lammpsbin" suffix
+described below.  Again, this file will be written in parallel and
+have the same binary format as if it were written without MPI-IO.
+
 .. warning::
 
-   The MPIIO package is currently unmaintained and has become
+   The MPIIO package within LAMMPS is currently unmaintained and has
-   unreliable. Use with caution.
+   become unreliable. Use with caution.
 
-Note that MPI-IO dump files are one large file which all processors
+----------
-write to.  You thus cannot use the "%" wildcard character described
-above in the filename since that specifies generation of multiple files.
-You can use the ".bin" or ".lammpsbin" suffix described below in an
-MPI-IO dump file; again this file will be written in parallel and have
-the same binary format as if it were written without MPI-IO.
 
-If the filename ends with ".bin" or ".lammpsbin", the dump file (or
+Compression of dump file data:
-files, if "\*" or "%" is also used) is written in binary format.  A
+
-binary dump file will be about the same size as a text version, but will
+If the specified filename ends with ".bin" or ".lammpsbin", the dump
-typically write out much faster.  Of course, when post-processing, you
+file (or files, if "\*" or "%" is also used) is written in binary
-will need to convert it back to text format (see the :ref:`binary2txt
+format.  A binary dump file will be about the same size as a text
-tool <binary>`) or write your own code to read the binary file.  The
+version, but will typically write out much faster.  Of course, when
-format of the binary file can be understood by looking at the
+post-processing, you will need to convert it back to text format (see
-:file:`tools/binary2txt.cpp` file.  This option is only available for
+the :ref:`binary2txt tool <binary>`) or write your own code to read
-the *atom* and *custom* styles.
+the binary file.  The format of the binary file can be understood by
+looking at the :file:`tools/binary2txt.cpp` file.  This option is only
+available for the *atom* and *custom* styles.
 
 If the filename ends with ".gz", the dump file (or files, if "\*" or "%"
 is also used) is written in gzipped format.  A gzipped dump file will be
@@ -589,19 +643,40 @@ about :math:`3\times` smaller than the text version, but will also take
 longer to write.  This option is not available for the *dcd* and *xtc*
 styles.
 
+Note that styles that end with *gz* are identical in command syntax to
+the corresponding styles without "gz", however, they generate
+compressed files using the zlib library. Thus the filename suffix
+".gz" is mandatory. This is an alternative approach to writing
+compressed files via a pipe, as done by the regular dump styles, which
+may be required on clusters where the interface to the high-speed
+network disallows using the fork() library call (which is needed for a
+pipe).  For the remainder of this page, you should thus consider the
+*atom* and *atom/gz* styles (etc.) to be inter-changeable, with the
+exception of the required filename suffix.
+
+Similarly, styles that end with *zstd* are identical to the gz styles,
+but use the Zstd compression library instead and require a ".zst"
+suffix. See the :doc:`dump_modify <dump_modify>` page for details on
+how to control the compression level in both variants.
+
 ----------
 
-Note that in the discussion which follows, for styles which can
+Arguments for different styles:
-reference values from a compute or fix or custom atom property, like the
+
-*custom*\ , *cfg*\ , or *local* styles, the bracketed index :math:`i`
+The sections below describe per-atom, local, and per grid cell
-can be specified using a wildcard asterisk with the index to effectively
+attributes which can be used as arguments to the various styles.
-specify multiple values.  This takes the form "\*" or "\*n" or "m\*" or
+
-"m\*n".  If :math:`N` is the number of columns in the array, then an
+Note that in the discussion below, for styles which can reference
-asterisk with no numeric values means all column indices from 1 to
+values from a compute or fix or custom atom property, like the
-:math:`N`.  A leading asterisk means all indices from 1 to n
+*custom*\ , *cfg*\ , *grid* or *local* styles, the bracketed index
-(inclusive).  A trailing asterisk means all indices from m to :math:`N`
+:math:`i` can be specified using a wildcard asterisk with the index to
-(inclusive).  A middle asterisk means all indices from m to n
+effectively specify multiple values.  This takes the form "\*" or
-(inclusive).
+"\*n" or "m\*" or "m\*n".  If :math:`N` is the number of columns in
+the array, then an asterisk with no numeric values means all column
+indices from 1 to :math:`N`.  A leading asterisk means all indices
+from 1 to n (inclusive).  A trailing asterisk means all indices from m
+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 columns of the array
 had been listed one by one.  For example, these two dump commands are
@@ -617,63 +692,7 @@ command creates a per-atom array with six columns:
 
 ----------
 
-This section explains the local attributes that can be specified as
+Per-atom attributes used as arguments to the *custom* and *cfg* styles:
-part of the *local* style.
-
-The *index* attribute can be used to generate an index number from 1
-to :math:`N` for each line written into the dump file, where :math:`N` is the
-total number of local datums from all processors, or lines of output that
-will appear in the snapshot.  Note that because data from different
-processors depend on what atoms they currently own, and atoms migrate
-between processor, there is no guarantee that the same index will be
-used for the same info (e.g., a particular bond) in successive snapshots.
-
-The *c_ID* and *c_ID[I]* attributes allow local vectors or arrays
-calculated by a :doc:`compute <compute>` to be output.  The ID in the
-attribute should be replaced by the actual ID of the compute that has
-been defined previously in the input script.  See the
-:doc:`compute <compute>` command for details.  There are computes for
-calculating local information such as indices, types, and energies for
-bonds and angles.
-
-Note that computes which calculate global or per-atom quantities, as
-opposed to local quantities, cannot be output in a dump local command.
-Instead, global quantities can be output by the :doc:`thermo_style
-custom <thermo_style>` command, and per-atom quantities can be output
-by the dump custom command.
-
-If *c_ID* is used as a attribute, then the local vector calculated by
-the compute is printed.  If *c_ID[i]* is used, then :math:`i` must be in the
-range from :math:`1-M`, which will print the Ith column of the local array
-with :math:`M` columns calculated by the compute.  See the discussion above
-for how :math:`i` can be specified with a wildcard asterisk to effectively
-specify multiple values.
-
-The *f_ID* and *f_ID[I]* attributes allow local vectors or arrays
-calculated by a :doc:`fix <fix>` to be output.  The ID in the attribute
-should be replaced by the actual ID of the fix that has been defined
-previously in the input script.
-
-If *f_ID* is used as a attribute, then the local vector calculated by
-the fix is printed.  If *f_ID[i]* is used, then :math:`i` must be in the
-range :math:`1`--:math:`M`, which will print the :math:`i`\ th column of the
-local with :math:`M` columns calculated by the fix.  See the discussion above
-for how :math:`i` can be specified with a wildcard asterisk to effectively
-specify multiple values.
-
-Here is an example of how to dump bond info for a system, including
-the distance and energy of each bond:
-
-.. code-block:: LAMMPS
-
-   compute 1 all property/local batom1 batom2 btype
-   compute 2 all bond/local dist eng
-   dump 1 all local 1000 tmp.dump index c_1[1] c_1[2] c_1[3] c_2[1] c_2[2]
-
-----------
-
-This section explains the atom attributes that can be specified as
-part of the *custom* and *cfg* styles.
 
 The *id*, *mol*, *proc*, *procp1*, *type*, *element*, *mass*, *vx*,
 *vy*, *vz*, *fx*, *fy*, *fz*, *q* attributes are self-explanatory.
@@ -808,6 +827,97 @@ which could then be output into dump files.
 
 ----------
 
+Attributes used as arguments to the *local* style:
+
+The *index* attribute can be used to generate an index number from 1
+to N for each line written into the dump file, where N is the total
+number of local datums from all processors, or lines of output that
+will appear in the snapshot.  Note that because data from different
+processors depend on what atoms they currently own, and atoms migrate
+between processor, there is no guarantee that the same index will be
+used for the same info (e.g. a particular bond) in successive
+snapshots.
+
+The *c_ID* and *c_ID[I]* attributes allow local vectors or arrays
+calculated by a :doc:`compute <compute>` to be output.  The ID in the
+attribute should be replaced by the actual ID of the compute that has
+been defined previously in the input script.  See the
+:doc:`compute <compute>` command for details.  There are computes for
+calculating local information such as indices, types, and energies for
+bonds and angles.
+
+Note that computes which calculate global or per-atom quantities, as
+opposed to local quantities, cannot be output in a dump local command.
+Instead, global quantities can be output by the :doc:`thermo_style
+custom <thermo_style>` command, and per-atom quantities can be output
+by the dump custom command.
+
+If *c_ID* is used as a attribute, then the local vector calculated by
+the compute is printed.  If *c_ID[I]* is used, then I must be in the
+range from 1-M, which will print the Ith column of the local array
+with M columns calculated by the compute.  See the discussion above
+for how I can be specified with a wildcard asterisk to effectively
+specify multiple values.
+
+The *f_ID* and *f_ID[I]* attributes allow local vectors or arrays
+calculated by a :doc:`fix <fix>` to be output.  The ID in the attribute
+should be replaced by the actual ID of the fix that has been defined
+previously in the input script.
+
+If *f_ID* is used as a attribute, then the local vector calculated by
+the fix is printed.  If *f_ID[I]* is used, then I must be in the
+range from 1-M, which will print the Ith column of the local with M
+columns calculated by the fix.  See the discussion above for how I can
+be specified with a wildcard asterisk to effectively specify multiple
+values.
+
+Here is an example of how to dump bond info for a system, including
+the distance and energy of each bond:
+
+.. code-block:: LAMMPS
+
+   compute 1 all property/local batom1 batom2 btype
+   compute 2 all bond/local dist eng
+   dump 1 all local 1000 tmp.dump index c_1[1] c_1[2] c_1[3] c_2[1] c_2[2]
+
+----------
+
+Attributes used as arguments to the *grid* and *grid/vtk* styles:
+
+The attributes that begin with *c_ID* and *f_ID* both take
+colon-separated fields *gname* and *dname*.  These refer to a grid
+name and data field name which is defined by the compute or fix.  Note
+that a compute or fix can define one or more grids (of different
+sizes) and one or more data fields for each of those grids.  The sizes
+of all grids output in a single dump grid command must be the same.
+
+The *c_ID:gname:dname* and *c_ID:gname:dname[I]* attributes allow
+per-grid vectors or arrays calculated by a :doc:`compute <compute>` to
+be output.  The ID in the attribute should be replaced by the actual
+ID of the compute that has been defined previously in the input
+script.
+
+If *c_ID:gname:dname* is used as a attribute, then the per-grid vector
+calculated by the compute is printed.  If *c_ID:gname:dname[I]* is
+used, then I must be in the range from 1-M, which will print the Ith
+column of the per-grid array with M columns calculated by the compute.
+See the discussion above for how I can be specified with a wildcard
+asterisk to effectively specify multiple values.
+
+The *f_ID:gname:dname* and *f_ID:gname:dname[I]* attributes allow
+per-grid vectors or arrays calculated by a :doc:`fix <fix>` to be
+output.  The ID in the attribute should be replaced by the actual ID
+of the fix that has been defined previously in the input script.
+
+If *f_ID:gname:dname* is used as a attribute, then the per-grid vector
+calculated by the fix is printed.  If *f_ID:gname:dname[I]* is used,
+then I must be in the range from 1-M, which will print the Ith column
+of the per-grid with M columns calculated by the fix.  See the
+discussion above for how I can be specified with a wildcard asterisk
+to effectively specify multiple values.
+
+----------
+
 Restrictions
 """"""""""""
 
@@ -816,9 +926,9 @@ To write gzipped dump files, you must either compile LAMMPS with the
 See the :doc:`Build settings <Build_settings>` page for details.
 
 While a dump command is active (i.e., has not been stopped by using
-the :doc:`undump command <undump>`), no commands may be used that will change
+the :doc:`undump command <undump>`), no commands may be used that will
-the timestep (e.g., :doc:`reset_timestep <reset_timestep>`).  LAMMPS
+change the timestep (e.g., :doc:`reset_timestep <reset_timestep>`).
-will terminate with an error otherwise.
+LAMMPS will terminate with an error otherwise.
 
 The *atom/gz*, *cfg/gz*, *custom/gz*, and *xyz/gz* styles are part of
 the COMPRESS package.  They are only enabled if LAMMPS was built with