Merge branch 'develop' into Iximiel/develop

.gitattributes

@@ -3,3 +3,9 @@
 .github export-ignore
 .lgtm.yml export-ignore
 SECURITY.md export-ignore
+*       text=auto
+*.jpg   -text
+*.pdf   -text
+*.gz    -text
+*.png   -text
+*.ps    -text

.github/CONTRIBUTING.md

@@ -5,8 +5,8 @@ Thank your for considering to contribute to the LAMMPS software project.
 The following is a set of guidelines as well as explanations of policies and work flows for contributing to the LAMMPS molecular dynamics software project. These guidelines focus on submitting issues or pull requests on the LAMMPS GitHub project.
 
 Thus please also have a look at:
-* [The guide for submitting new features in the LAMMPS manual](https://lammps.sandia.gov/doc/Modify_contribute.html)
+* [The guide for submitting new features in the LAMMPS manual](https://www.lammps.org/doc/Modify_contribute.html)
-* [The guide on programming style and requirement in the LAMMPS manual](https://lammps.sandia.gov/doc/Modify_contribute.html)
+* [The guide on programming style and requirement in the LAMMPS manual](https://www.lammps.org/doc/Modify_style.html)
 * [The GitHub tutorial in the LAMMPS manual](http://lammps.sandia.gov/doc/Howto_github.html)
 
 ## Table of Contents

.github/workflows/compile-msvc.yml

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

.github/workflows/unittest-macos.yml

@@ -37,6 +37,7 @@ jobs:
       working-directory: build
       run: |
         ccache -z
+        python3 -m pip install pyyaml
         cmake -C ../cmake/presets/clang.cmake \
               -C ../cmake/presets/most.cmake \
               -D CMAKE_CXX_COMPILER_LAUNCHER=ccache \

.gitignore

@@ -12,6 +12,7 @@
 *.sif
 *.dll
 *.pyc
+*.whl
 a.out
 __pycache__
 

bench/README

@@ -4,10 +4,8 @@ This directory contains 5 benchmark problems which are discussed in
 the Benchmark section of the LAMMPS documentation, and on the
 Benchmark page of the LAMMPS WWW site (https://www.lammps.org/bench.html).
 
-This directory also has several sub-directories:
+This directory also has one sub-directories:
 
-FERMI           benchmark scripts for desktop machine with Fermi GPUs (Tesla)
-KEPLER          benchmark scripts for GPU cluster with Kepler GPUs
 POTENTIALS      benchmarks scripts for various potentials in LAMMPS
 
 The results for all of these benchmarks are displayed and discussed on

cmake/CMakeLists.txt

@@ -16,9 +16,13 @@ endif()
 
 project(lammps CXX)
 set(SOVERSION 0)
+get_property(BUILD_IS_MULTI_CONFIG GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
 
 get_filename_component(LAMMPS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/.. ABSOLUTE)
 get_filename_component(LAMMPS_LIB_BINARY_DIR ${CMAKE_BINARY_DIR}/lib ABSOLUTE)
+# collect all executables and shared libs in the top level build folder
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
+set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
 
 set(LAMMPS_SOURCE_DIR     ${LAMMPS_DIR}/src)
 set(LAMMPS_LIB_SOURCE_DIR ${LAMMPS_DIR}/lib)
@@ -101,8 +105,28 @@ if(CMAKE_CXX_COMPILER_ID STREQUAL "Intel")
   endif()
 endif()
 
+# silence excessive warnings for new Intel Compilers
+if(CMAKE_CXX_COMPILER_ID STREQUAL "IntelLLVM")
+  set(CMAKE_TUNE_DEFAULT "-Wno-tautological-constant-compare")
+endif()
+
+# silence excessive warnings for PGI/NVHPC compilers
+if((CMAKE_CXX_COMPILER_ID STREQUAL "NVHPC") OR (CMAKE_CXX_COMPILER_ID STREQUAL "PGI"))
+  set(CMAKE_TUNE_DEFAULT "-Minform=severe")
+endif()
+
+# silence nvcc warnings
+if((PKG_KOKKOS) AND (Kokkos_ENABLE_CUDA))
+  set(CMAKE_TUNE_DEFAULT "${CMAKE_TUNE_DEFAULT} -Xcudafe --diag_suppress=unrecognized_pragma")
+endif()
+
 # we require C++11 without extensions. Kokkos requires at least C++14 (currently)
-set(CMAKE_CXX_STANDARD 11)
+if(NOT CMAKE_CXX_STANDARD)
+  set(CMAKE_CXX_STANDARD 11)
+endif()
+if(CMAKE_CXX_STANDARD LESS 11)
+  message(FATAL_ERROR "C++ standard must be set to at least 11")
+endif()
 if(PKG_KOKKOS AND (CMAKE_CXX_STANDARD LESS 14))
   set(CMAKE_CXX_STANDARD 14)
 endif()
@@ -168,6 +192,7 @@ set(STANDARD_PACKAGES
   AWPMD
   BOCS
   BODY
+  BPM
   BROWNIAN
   CG-DNA
   CG-SDK
@@ -204,7 +229,6 @@ set(STANDARD_PACKAGES
   MDI
   MEAM
   MESONT
-  MESSAGE
   MGPT
   MISC
   ML-HDNNP
@@ -280,35 +304,19 @@ if(BUILD_MPI)
   # We use a non-standard procedure to cross-compile with MPI on Windows
   if((CMAKE_SYSTEM_NAME STREQUAL "Windows") AND CMAKE_CROSSCOMPILING)
     include(MPI4WIN)
-    target_link_libraries(lammps PUBLIC MPI::MPI_CXX)
   else()
     find_package(MPI REQUIRED)
-    target_link_libraries(lammps PUBLIC MPI::MPI_CXX)
     option(LAMMPS_LONGLONG_TO_LONG "Workaround if your system or MPI version does not recognize 'long long' data types" OFF)
     if(LAMMPS_LONGLONG_TO_LONG)
       target_compile_definitions(lammps PRIVATE -DLAMMPS_LONGLONG_TO_LONG)
     endif()
   endif()
+  target_link_libraries(lammps PUBLIC MPI::MPI_CXX)
 else()
-  file(GLOB MPI_SOURCES ${LAMMPS_SOURCE_DIR}/STUBS/mpi.cpp)
+  target_sources(lammps PRIVATE ${LAMMPS_SOURCE_DIR}/STUBS/mpi.cpp)
-  add_library(mpi_stubs STATIC ${MPI_SOURCES})
+  add_library(mpi_stubs INTERFACE)
-  set_target_properties(mpi_stubs PROPERTIES OUTPUT_NAME lammps_mpi_stubs${LAMMPS_MACHINE})
+  target_include_directories(mpi_stubs INTERFACE $<BUILD_INTERFACE:${LAMMPS_SOURCE_DIR}/STUBS>)
-  target_include_directories(mpi_stubs PUBLIC $<BUILD_INTERFACE:${LAMMPS_SOURCE_DIR}/STUBS>)
-  if(BUILD_SHARED_LIBS)
-    target_link_libraries(lammps PRIVATE mpi_stubs)
-    if(MSVC)
-      target_link_libraries(lmp PRIVATE mpi_stubs)
-      target_include_directories(lmp INTERFACE $<BUILD_INTERFACE:${LAMMPS_SOURCE_DIR}/STUBS>)
-      target_compile_definitions(lmp INTERFACE $<INSTALL_INTERFACE:LAMMPS_LIB_NO_MPI>)
-    endif()
-    target_include_directories(lammps INTERFACE $<BUILD_INTERFACE:${LAMMPS_SOURCE_DIR}/STUBS>)
-    target_compile_definitions(lammps INTERFACE $<INSTALL_INTERFACE:LAMMPS_LIB_NO_MPI>)
-  else()
-    target_include_directories(lammps INTERFACE $<BUILD_INTERFACE:${LAMMPS_SOURCE_DIR}/STUBS>)
-    target_compile_definitions(lammps INTERFACE $<INSTALL_INTERFACE:LAMMPS_LIB_NO_MPI>)
   target_link_libraries(lammps PUBLIC mpi_stubs)
-  endif()
-  add_library(MPI::MPI_CXX ALIAS mpi_stubs)
 endif()
 
 set(LAMMPS_SIZES "smallbig" CACHE STRING "LAMMPS integer sizes (smallsmall: all 32-bit, smallbig: 64-bit #atoms #timesteps, bigbig: also 64-bit imageint, 64-bit atom ids)")
@@ -339,7 +347,6 @@ pkg_depends(ML-IAP ML-SNAP)
 pkg_depends(MPIIO MPI)
 pkg_depends(ATC MANYBODY)
 pkg_depends(LATBOLTZ MPI)
-pkg_depends(PHONON KSPACE)
 pkg_depends(SCAFACOS MPI)
 pkg_depends(DIELECTRIC KSPACE)
 pkg_depends(DIELECTRIC EXTRA-PAIR)
@@ -373,11 +380,13 @@ if(BUILD_OMP)
       ((CMAKE_CXX_COMPILER_ID STREQUAL "Intel") AND (CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 19.0)))
     # GCC 9.x and later plus Clang 10.x and later implement strict OpenMP 4.0 semantics for consts.
     # Intel 18.0 was tested to support both, so we switch to OpenMP 4+ from 19.x onward to be safe.
-    target_compile_definitions(lammps PRIVATE -DLAMMPS_OMP_COMPAT=4)
+    set(LAMMPS_OMP_COMPAT_LEVEL 4)
   else()
-    target_compile_definitions(lammps PRIVATE -DLAMMPS_OMP_COMPAT=3)
+    set(LAMMPS_OMP_COMPAT_LEVEL 3)
   endif()
+  target_compile_definitions(lammps PRIVATE -DLAMMPS_OMP_COMPAT=${LAMMPS_OMP_COMPAT_LEVEL})
   target_link_libraries(lammps PRIVATE OpenMP::OpenMP_CXX)
+  target_link_libraries(lmp PRIVATE OpenMP::OpenMP_CXX)
 endif()
 
 if(PKG_MSCG OR PKG_ATC OR PKG_AWPMD OR PKG_ML-QUIP OR PKG_LATTE)
@@ -462,7 +471,7 @@ else()
 endif()
 
 foreach(PKG_WITH_INCL KSPACE PYTHON ML-IAP VORONOI COLVARS ML-HDNNP MDI MOLFILE NETCDF
-        PLUMED QMMM ML-QUIP SCAFACOS MACHDYN VTK KIM LATTE MESSAGE MSCG COMPRESS ML-PACE)
+        PLUMED QMMM ML-QUIP SCAFACOS MACHDYN VTK KIM LATTE MSCG COMPRESS ML-PACE)
   if(PKG_${PKG_WITH_INCL})
     include(Packages/${PKG_WITH_INCL})
   endif()
@@ -479,6 +488,7 @@ set(CMAKE_TUNE_FLAGS "${CMAKE_TUNE_DEFAULT}" CACHE STRING "Compiler and machine
 separate_arguments(CMAKE_TUNE_FLAGS)
 foreach(_FLAG ${CMAKE_TUNE_FLAGS})
   target_compile_options(lammps PRIVATE ${_FLAG})
+  target_compile_options(lmp PRIVATE ${_FLAG})
 endforeach()
 ########################################################################
 # Basic system tests (standard libraries, headers, functions, types)   #
@@ -591,11 +601,10 @@ if(PKG_ATC)
   if(LAMMPS_SIZES STREQUAL "BIGBIG")
     message(FATAL_ERROR "The ATC Package is not compatible with -DLAMMPS_BIGBIG")
   endif()
-  target_link_libraries(atc PRIVATE ${LAPACK_LIBRARIES})
   if(BUILD_MPI)
-    target_link_libraries(atc PRIVATE MPI::MPI_CXX)
+    target_link_libraries(atc PRIVATE ${LAPACK_LIBRARIES} MPI::MPI_CXX)
   else()
-    target_link_libraries(atc PRIVATE mpi_stubs)
+    target_link_libraries(atc PRIVATE ${LAPACK_LIBRARIES} mpi_stubs)
   endif()
   target_include_directories(atc PRIVATE ${LAMMPS_SOURCE_DIR})
   target_compile_definitions(atc PRIVATE -DLAMMPS_${LAMMPS_SIZES})
@@ -609,7 +618,7 @@ endif()
 # packages which selectively include variants based on enabled styles
 # e.g. accelerator packages
 ######################################################################
-foreach(PKG_WITH_INCL CORESHELL QEQ OPENMP DPD-SMOOTH KOKKOS OPT INTEL GPU)
+foreach(PKG_WITH_INCL CORESHELL DPD-SMOOTH PHONON QEQ OPENMP KOKKOS OPT INTEL GPU)
   if(PKG_${PKG_WITH_INCL})
     include(Packages/${PKG_WITH_INCL})
   endif()
@@ -691,6 +700,7 @@ endif()
 
 set_target_properties(lammps PROPERTIES OUTPUT_NAME lammps${LAMMPS_MACHINE})
 set_target_properties(lammps PROPERTIES SOVERSION ${SOVERSION})
+set_target_properties(lammps PROPERTIES PREFIX "lib")
 target_include_directories(lammps PUBLIC $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}/lammps>)
 file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/includes/lammps)
 foreach(_HEADER ${LAMMPS_CXX_HEADERS})
@@ -710,6 +720,9 @@ foreach(_DEF ${LAMMPS_DEFINES})
 endforeach()
 if(BUILD_SHARED_LIBS)
   install(TARGETS lammps EXPORT LAMMPS_Targets LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
+  if(NOT BUILD_MPI)
+    install(TARGETS mpi_stubs EXPORT LAMMPS_Targets LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR} ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR})
+  endif()
   configure_file(pkgconfig/liblammps.pc.in ${CMAKE_CURRENT_BINARY_DIR}/liblammps${LAMMPS_MACHINE}.pc @ONLY)
   install(FILES ${CMAKE_CURRENT_BINARY_DIR}/liblammps${LAMMPS_MACHINE}.pc DESTINATION ${CMAKE_INSTALL_LIBDIR}/pkgconfig)
   install(EXPORT LAMMPS_Targets FILE LAMMPS_Targets.cmake NAMESPACE LAMMPS:: DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/LAMMPS)
@@ -749,7 +762,7 @@ install(
 if(BUILD_SHARED_LIBS)
   if(CMAKE_VERSION VERSION_LESS 3.12)
     # adjust so we find Python 3 versions before Python 2 on old systems with old CMake
-    set(Python_ADDITIONAL_VERSIONS 3.9 3.8 3.7 3.6 3.5)
+    set(Python_ADDITIONAL_VERSIONS 3.12 3.11 3.10 3.9 3.8 3.7 3.6)
     find_package(PythonInterp) # Deprecated since version 3.12
     if(PYTHONINTERP_FOUND)
         set(Python_EXECUTABLE ${PYTHON_EXECUTABLE})
@@ -757,13 +770,15 @@ if(BUILD_SHARED_LIBS)
   else()
     find_package(Python COMPONENTS Interpreter)
   endif()
+  if(BUILD_IS_MULTI_CONFIG)
+    set(LIBLAMMPS_SHARED_BINARY ${CMAKE_BINARY_DIR}/$<CONFIG>/liblammps${LAMMPS_MACHINE}${CMAKE_SHARED_LIBRARY_SUFFIX})
+  else()
+    set(LIBLAMMPS_SHARED_BINARY ${CMAKE_BINARY_DIR}/liblammps${LAMMPS_MACHINE}${CMAKE_SHARED_LIBRARY_SUFFIX})
+  endif()
   if(Python_EXECUTABLE)
     add_custom_target(
       install-python ${CMAKE_COMMAND} -E remove_directory build
-      COMMAND ${Python_EXECUTABLE} install.py -v ${LAMMPS_SOURCE_DIR}/version.h
+      COMMAND ${Python_EXECUTABLE} ${LAMMPS_PYTHON_DIR}/install.py -p ${LAMMPS_PYTHON_DIR}/lammps -l ${LIBLAMMPS_SHARED_BINARY}
-      -p ${LAMMPS_PYTHON_DIR}/lammps
-      -l ${CMAKE_BINARY_DIR}/liblammps${LAMMPS_MACHINE}${CMAKE_SHARED_LIBRARY_SUFFIX}
-      WORKING_DIRECTORY  ${LAMMPS_PYTHON_DIR}
       COMMENT "Installing LAMMPS Python module")
   else()
     add_custom_target(
@@ -808,7 +823,6 @@ if(ClangFormat_FOUND)
 endif()
 
 get_target_property(DEFINES lammps COMPILE_DEFINITIONS)
-get_property(BUILD_IS_MULTI_CONFIG GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
 if(BUILD_IS_MULTI_CONFIG)
   set(LAMMPS_BUILD_TYPE "Multi-Config")
 else()
@@ -817,6 +831,7 @@ endif()
 include(FeatureSummary)
 feature_summary(DESCRIPTION "The following tools and libraries have been found and configured:" WHAT PACKAGES_FOUND)
 message(STATUS "<<< Build configuration >>>
+   LAMMPS Version:   ${PROJECT_VERSION}
    Operating System: ${CMAKE_SYSTEM_NAME} ${CMAKE_LINUX_DISTRO} ${CMAKE_DISTRO_VERSION}
    Build type:       ${LAMMPS_BUILD_TYPE}
    Install path:     ${CMAKE_INSTALL_PREFIX}

cmake/CMakeSettings.json

@@ -6,7 +6,7 @@
       "configurationType": "Debug",
       "buildRoot": "${workspaceRoot}\\build\\${name}",
       "installRoot": "${workspaceRoot}\\install\\${name}",
-      "cmakeCommandArgs": "-S ${workspaceRoot}\\cmake -C ${workspaceRoot}\\cmake\\presets\\windows.cmake -DENABLE_TESTING=on",
+      "cmakeCommandArgs": "-C ${workspaceRoot}\\cmake\\presets\\windows.cmake",
       "buildCommandArgs": "",
       "ctestCommandArgs": "",
       "inheritEnvironments": [ "msvc_x64_x64" ],
@@ -25,6 +25,54 @@
           "name": "LAMMPS_EXCEPTIONS",
           "value": "True",
           "type": "BOOL"
+        },
+        {
+          "name": "PKG_PYTHON",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "ENABLE_TESTING",
+          "value": "True",
+          "type": "BOOL"
+        }
+      ]
+    },
+    {
+      "name": "x64-Release-MSVC",
+      "generator": "Ninja",
+      "configurationType": "Release",
+      "buildRoot": "${workspaceRoot}\\build\\${name}",
+      "installRoot": "${workspaceRoot}\\install\\${name}",
+      "cmakeCommandArgs": "-C ${workspaceRoot}\\cmake\\presets\\windows.cmake",
+      "buildCommandArgs": "",
+      "ctestCommandArgs": "",
+      "inheritEnvironments": [ "msvc_x64_x64" ],
+      "variables": [
+        {
+          "name": "BUILD_SHARED_LIBS",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "BUILD_TOOLS",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "LAMMPS_EXCEPTIONS",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "PKG_PYTHON",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "ENABLE_TESTING",
+          "value": "True",
+          "type": "BOOL"
         }
       ]
     },
@@ -34,11 +82,16 @@
       "configurationType": "Debug",
       "buildRoot": "${workspaceRoot}\\build\\${name}",
       "installRoot": "${workspaceRoot}\\install\\${name}",
-      "cmakeCommandArgs": "-S ${workspaceRoot}\\cmake -C ${workspaceRoot}\\cmake\\presets\\windows.cmake -DENABLE_TESTING=on",
+      "cmakeCommandArgs": "-C ${workspaceRoot}\\cmake\\presets\\windows.cmake -DCMAKE_C_COMPILER=clang-cl.exe -DCMAKE_CXX_COMPILER=clang-cl.exe",
       "buildCommandArgs": "",
       "ctestCommandArgs": "",
       "inheritEnvironments": [ "clang_cl_x64" ],
       "variables": [
+        {
+          "name": "BUILD_SHARED_LIBS",
+          "value": "True",
+          "type": "BOOL"
+        },
         {
           "name": "BUILD_TOOLS",
           "value": "True",
@@ -48,19 +101,29 @@
           "name": "LAMMPS_EXCEPTIONS",
           "value": "True",
           "type": "BOOL"
+        },
+        {
+          "name": "PKG_PYTHON",
+          "value": "True",
+          "type": "BOOL"
+        },
+        {
+          "name": "ENABLE_TESTING",
+          "value": "True",
+          "type": "BOOL"
         }
       ]
     },
     {
-      "name": "x64-Debug-OneAPI",
+      "name": "x64-Release-Clang",
       "generator": "Ninja",
-      "configurationType": "Debug",
+      "configurationType": "Release",
       "buildRoot": "${workspaceRoot}\\build\\${name}",
       "installRoot": "${workspaceRoot}\\install\\${name}",
-      "cmakeCommandArgs": "-S ${workspaceRoot}\\cmake -C ${workspaceRoot}\\cmake\\presets\\windows.cmake -DENABLE_TESTING=on -DCMAKE_CXX_COMPILER=icx -DCMAKE_C_COMPILER=icx -DBUILD_MPI=off",
+      "cmakeCommandArgs": "-C ${workspaceRoot}\\cmake\\presets\\windows.cmake -DCMAKE_C_COMPILER=clang-cl.exe -DCMAKE_CXX_COMPILER=clang-cl.exe",
       "buildCommandArgs": "",
       "ctestCommandArgs": "",
-      "inheritEnvironments": [ "msvc_x64_x64" ],
+      "inheritEnvironments": [ "clang_cl_x64" ],
       "variables": [
         {
           "name": "BUILD_SHARED_LIBS",
@@ -76,32 +139,14 @@
           "name": "LAMMPS_EXCEPTIONS",
           "value": "True",
           "type": "BOOL"
-        }
-      ]
         },
         {
-      "name": "x64-Debug-Intel",
+          "name": "PKG_PYTHON",
-      "generator": "Ninja",
-      "configurationType": "Debug",
-      "buildRoot": "${workspaceRoot}\\build\\${name}",
-      "installRoot": "${workspaceRoot}\\install\\${name}",
-      "cmakeCommandArgs": "-S ${workspaceRoot}\\cmake -C ${workspaceRoot}\\cmake\\presets\\windows.cmake -DENABLE_TESTING=off -DCMAKE_CXX_COMPILER=icl -DCMAKE_C_COMPILER=icl -DCMAKE_Fortran_COMPILER=ifort -DBUILD_MPI=off",
-      "buildCommandArgs": "",
-      "ctestCommandArgs": "",
-      "inheritEnvironments": [ "msvc_x64_x64" ],
-      "variables": [
-        {
-          "name": "BUILD_SHARED_LIBS",
           "value": "True",
           "type": "BOOL"
         },
         {
-          "name": "BUILD_TOOLS",
+          "name": "ENABLE_TESTING",
-          "value": "True",
-          "type": "BOOL"
-        },
-        {
-          "name": "LAMMPS_EXCEPTIONS",
           "value": "True",
           "type": "BOOL"
         }

cmake/Modules/Documentation.cmake

@@ -7,13 +7,13 @@ if(BUILD_DOC)
   # Sphinx 3.x requires at least Python 3.5
   if(CMAKE_VERSION VERSION_LESS 3.12)
     find_package(PythonInterp 3.5 REQUIRED)
-    set(VIRTUALENV ${PYTHON_EXECUTABLE} -m virtualenv -p ${PYTHON_EXECUTABLE})
+    set(VIRTUALENV ${PYTHON_EXECUTABLE} -m venv)
   else()
     find_package(Python3 REQUIRED COMPONENTS Interpreter)
     if(Python3_VERSION VERSION_LESS 3.5)
       message(FATAL_ERROR "Python 3.5 and up is required to build the HTML documentation")
     endif()
-    set(VIRTUALENV ${Python3_EXECUTABLE} -m virtualenv -p ${Python3_EXECUTABLE})
+    set(VIRTUALENV ${Python3_EXECUTABLE} -m venv)
   endif()
   find_package(Doxygen 1.8.10 REQUIRED)
 

cmake/Modules/FindCythonize.cmake

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

cmake/Modules/LAMMPSUtils.cmake

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

cmake/Modules/OpenCLLoader.cmake

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

cmake/Modules/Packages/COLVARS.cmake

@@ -19,6 +19,10 @@ endif()
 
 add_library(colvars STATIC ${COLVARS_SOURCES})
 target_compile_definitions(colvars PRIVATE -DCOLVARS_LAMMPS)
+separate_arguments(CMAKE_TUNE_FLAGS)
+foreach(_FLAG ${CMAKE_TUNE_FLAGS})
+  target_compile_options(colvars PRIVATE ${_FLAG})
+endforeach()
 set_target_properties(colvars PROPERTIES OUTPUT_NAME lammps_colvars${LAMMPS_MACHINE})
 target_include_directories(colvars PUBLIC ${LAMMPS_LIB_SOURCE_DIR}/colvars)
 # The line below is needed to locate math_eigen_impl.h

cmake/Modules/Packages/COMPRESS.cmake

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

cmake/Modules/Packages/GPU.cmake

@@ -30,7 +30,15 @@ file(GLOB GPU_LIB_SOURCES ${LAMMPS_LIB_SOURCE_DIR}/gpu/[^.]*.cpp)
 file(MAKE_DIRECTORY ${LAMMPS_LIB_BINARY_DIR}/gpu)
 
 if(GPU_API STREQUAL "CUDA")
+  find_package(CUDA QUIET)
+  # augment search path for CUDA toolkit libraries to include the stub versions. Needed to find libcuda.so on machines without a CUDA driver installation
+  if(CUDA_FOUND)
+    set(CMAKE_LIBRARY_PATH "${CUDA_TOOLKIT_ROOT_DIR}/lib64/stubs;${CUDA_TOOLKIT_ROOT_DIR}/lib/stubs;${CUDA_TOOLKIT_ROOT_DIR}/lib64;${CUDA_TOOLKIT_ROOT_DIR}/lib;${CMAKE_LIBRARY_PATH}")
     find_package(CUDA REQUIRED)
+  else()
+    message(FATAL_ERROR "CUDA Toolkit not found")
+  endif()
+
   find_program(BIN2C bin2c)
   if(NOT BIN2C)
     message(FATAL_ERROR "Could not find bin2c, use -DBIN2C=/path/to/bin2c to help cmake finding it.")
@@ -72,14 +80,14 @@ if(GPU_API STREQUAL "CUDA")
   # --arch translates directly instead of JIT, so this should be for the preferred or most common architecture
   set(GPU_CUDA_GENCODE "-arch=${GPU_ARCH}")
 
-  # apply the following to build "fat" CUDA binaries only for known CUDA toolkits
+  # apply the following to build "fat" CUDA binaries only for known CUDA toolkits since version 8.0
-  if(CUDA_VERSION VERSION_GREATER_EQUAL "12.0")
+  # only the Kepler achitecture and beyond is supported
-    message(WARNING "Untested CUDA Toolkit version. Use at your own risk")
+  if(CUDA_VERSION VERSION_LESS 8.0)
+    message(FATAL_ERROR "CUDA Toolkit version 8.0 or later is required")
+  elseif(CUDA_VERSION VERSION_GREATER_EQUAL "12.0")
+    message(WARNING "Untested CUDA Toolkit version ${CUDA_VERSION}. Use at your own risk")
+    set(GPU_CUDA_GENCODE "-arch=all")
   else()
-    # Fermi (GPU Arch 2.x) is supported by CUDA 3.2 to CUDA 8.0
-    if((CUDA_VERSION VERSION_GREATER_EQUAL "3.2") AND (CUDA_VERSION VERSION_LESS "9.0"))
-      string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_20,code=[sm_20,compute_20] ")
-    endif()
     # Kepler (GPU Arch 3.0) is supported by CUDA 5 to CUDA 10.2
     if((CUDA_VERSION VERSION_GREATER_EQUAL "5.0") AND (CUDA_VERSION VERSION_LESS "11.0"))
       string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_30,code=[sm_30,compute_30] ")
@@ -112,6 +120,14 @@ if(GPU_API STREQUAL "CUDA")
     if(CUDA_VERSION VERSION_GREATER_EQUAL "11.1")
       string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_86,code=[sm_86,compute_86]")
     endif()
+    # Hopper (GPU Arch 9.0) is supported by CUDA 12.0? and later
+    if(CUDA_VERSION VERSION_GREATER_EQUAL "12.0")
+      string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_90,code=[sm_90,compute_90]")
+    endif()
+    #    # Lovelace (GPU Arch 9.x) is supported by CUDA 12.0? and later
+    #if(CUDA_VERSION VERSION_GREATER_EQUAL "12.0")
+    #  string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_9x,code=[sm_9x,compute_9x]")
+    #endif()
   endif()
 
   cuda_compile_fatbin(GPU_GEN_OBJS ${GPU_LIB_CU} OPTIONS ${CUDA_REQUEST_PIC}
@@ -249,13 +265,15 @@ elseif(GPU_API STREQUAL "HIP")
     find_package(CUDA REQUIRED)
     set(HIP_ARCH "sm_50" CACHE STRING "HIP primary CUDA architecture (e.g. sm_60)")
 
+    if(CUDA_VERSION VERSION_LESS 8.0)
+      message(FATAL_ERROR "CUDA Toolkit version 8.0 or later is required")
+    elseif(CUDA_VERSION VERSION_GREATER_EQUAL "12.0")
+      message(WARNING "Untested CUDA Toolkit version ${CUDA_VERSION}. Use at your own risk")
+      set(HIP_CUDA_GENCODE "-arch=all")
+    else()
       # build arch/gencode commands for nvcc based on CUDA toolkit version and use choice
       # --arch translates directly instead of JIT, so this should be for the preferred or most common architecture
       set(HIP_CUDA_GENCODE "-arch=${HIP_ARCH}")
-    # Fermi (GPU Arch 2.x) is supported by CUDA 3.2 to CUDA 8.0
-    if((CUDA_VERSION VERSION_GREATER_EQUAL "3.2") AND (CUDA_VERSION VERSION_LESS "9.0"))
-      string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_20,code=[sm_20,compute_20]")
-    endif()
       # Kepler (GPU Arch 3.0) is supported by CUDA 5 to CUDA 10.2
       if((CUDA_VERSION VERSION_GREATER_EQUAL "5.0") AND (CUDA_VERSION VERSION_LESS "11.0"))
         string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_30,code=[sm_30,compute_30]")
@@ -284,8 +302,10 @@ elseif(GPU_API STREQUAL "HIP")
       if(CUDA_VERSION VERSION_GREATER_EQUAL "11.0")
         string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_80,code=[sm_80,compute_80]")
       endif()
+      # Hopper (GPU Arch 9.0) is supported by CUDA 12.0? and later
       if(CUDA_VERSION VERSION_GREATER_EQUAL "12.0")
-      message(WARNING "Unsupported CUDA version. Use at your own risk.")
+        string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_90,code=[sm_90,compute_90]")
+      endif()
     endif()
   endif()
 
@@ -306,12 +326,12 @@ elseif(GPU_API STREQUAL "HIP")
 
         if(HIP_COMPILER STREQUAL "clang")
           add_custom_command(OUTPUT ${CUBIN_FILE}
-            VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --genco --offload-arch=${HIP_ARCH} -O3 -ffast-math -DUSE_HIP -D_${GPU_PREC_SETTING} -DLAMMPS_${LAMMPS_SIZES} -I${LAMMPS_LIB_SOURCE_DIR}/gpu -o ${CUBIN_FILE} ${CU_CPP_FILE}
+            VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --genco --offload-arch=${HIP_ARCH} -O3 -DUSE_HIP -D_${GPU_PREC_SETTING} -DLAMMPS_${LAMMPS_SIZES} -I${LAMMPS_LIB_SOURCE_DIR}/gpu -o ${CUBIN_FILE} ${CU_CPP_FILE}
             DEPENDS ${CU_CPP_FILE}
             COMMENT "Generating ${CU_NAME}.cubin")
         else()
           add_custom_command(OUTPUT ${CUBIN_FILE}
-            VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --genco -t="${HIP_ARCH}" -f=\"-O3 -ffast-math -DUSE_HIP -D_${GPU_PREC_SETTING} -DLAMMPS_${LAMMPS_SIZES} -I${LAMMPS_LIB_SOURCE_DIR}/gpu\" -o ${CUBIN_FILE} ${CU_CPP_FILE}
+            VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --genco -t="${HIP_ARCH}" -f=\"-O3 -DUSE_HIP -D_${GPU_PREC_SETTING} -DLAMMPS_${LAMMPS_SIZES} -I${LAMMPS_LIB_SOURCE_DIR}/gpu\" -o ${CUBIN_FILE} ${CU_CPP_FILE}
             DEPENDS ${CU_CPP_FILE}
             COMMENT "Generating ${CU_NAME}.cubin")
         endif()
@@ -339,6 +359,10 @@ elseif(GPU_API STREQUAL "HIP")
   target_link_libraries(gpu PRIVATE hip::host)
 
   if(HIP_USE_DEVICE_SORT)
+    if(HIP_PLATFORM STREQUAL "amd")
+      # newer version of ROCm (5.1+) require c++14 for rocprim
+      set_property(TARGET gpu PROPERTY CXX_STANDARD 14)
+    endif()
     # add hipCUB
     target_include_directories(gpu PRIVATE ${HIP_ROOT_DIR}/../include)
     target_compile_definitions(gpu PRIVATE -DUSE_HIP_DEVICE_SORT)
@@ -422,13 +446,12 @@ RegisterStylesExt(${GPU_SOURCES_DIR} gpu GPU_SOURCES)
 RegisterFixStyle(${GPU_SOURCES_DIR}/fix_gpu.h)
 
 get_property(GPU_SOURCES GLOBAL PROPERTY GPU_SOURCES)
-
+if(BUILD_MPI)
-if(NOT BUILD_MPI)
-  # mpistubs is aliased to MPI::MPI_CXX, but older versions of cmake won't work forward the include path
-  target_link_libraries(gpu PRIVATE mpi_stubs)
-else()
   target_link_libraries(gpu PRIVATE MPI::MPI_CXX)
+else()
+  target_link_libraries(gpu PRIVATE mpi_stubs)
 endif()
+
 target_compile_definitions(gpu PRIVATE -DLAMMPS_${LAMMPS_SIZES})
 set_target_properties(gpu PROPERTIES OUTPUT_NAME lammps_gpu${LAMMPS_MACHINE})
 target_sources(lammps PRIVATE ${GPU_SOURCES})

cmake/Modules/Packages/H5MD.cmake

@@ -1,5 +1,14 @@
 enable_language(C)
 
+# we don't use the parallel i/o interface.
+set(HDF5_PREFER_PARALLEL FALSE)
+
 find_package(HDF5 REQUIRED)
+
+# parallel HDF5 will import incompatible MPI headers with a serial build
+if((NOT BUILD_MPI) AND HDF5_IS_PARALLEL)
+  message(FATAL_ERROR "Serial LAMMPS build and parallel HDF5 library are not compatible")
+endif()
+
 target_link_libraries(h5md PRIVATE ${HDF5_LIBRARIES})
 target_include_directories(h5md PUBLIC ${HDF5_INCLUDE_DIRS})

cmake/Modules/Packages/KOKKOS.cmake

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

cmake/Modules/Packages/MACHDYN.cmake

@@ -36,3 +36,5 @@ endif()
 if((CMAKE_CXX_COMPILER_ID STREQUAL "PGI") OR (CMAKE_CXX_COMPILER_ID STREQUAL "NVHPC"))
   target_compile_definitions(lammps PRIVATE -DEIGEN_DONT_VECTORIZE)
 endif()
+
+target_compile_definitions(lammps PRIVATE -DEIGEN_NO_CUDA)

cmake/Modules/Packages/MDI.cmake

@@ -8,8 +8,8 @@ option(DOWNLOAD_MDI "Download and compile the MDI library instead of using an al
 
 if(DOWNLOAD_MDI)
   message(STATUS "MDI download requested - we will build our own")
-  set(MDI_URL "https://github.com/MolSSI-MDI/MDI_Library/archive/v1.2.9.tar.gz" CACHE STRING "URL for MDI tarball")
+  set(MDI_URL "https://github.com/MolSSI-MDI/MDI_Library/archive/v1.3.2.tar.gz" CACHE STRING "URL for MDI tarball")
-  set(MDI_MD5 "ddfa46d6ee15b4e59cfd527ec7212184" CACHE STRING "MD5 checksum for MDI tarball")
+  set(MDI_MD5 "836f5da400d8cff0f0e4435640f9454f" CACHE STRING "MD5 checksum for MDI tarball")
   mark_as_advanced(MDI_URL)
   mark_as_advanced(MDI_MD5)
   enable_language(C)

cmake/Modules/Packages/MESSAGE.cmake

@@ -1,31 +0,0 @@
-if(LAMMPS_SIZES STREQUAL "BIGBIG")
-  message(FATAL_ERROR "The MESSAGE Package is not compatible with -DLAMMPS_BIGBIG")
-endif()
-option(MESSAGE_ZMQ "Use ZeroMQ in MESSAGE package" OFF)
-file(GLOB_RECURSE cslib_SOURCES
-        ${LAMMPS_LIB_SOURCE_DIR}/message/cslib/[^.]*.cpp)
-
-add_library(cslib STATIC ${cslib_SOURCES})
-target_compile_definitions(cslib PRIVATE -DLAMMPS_${LAMMPS_SIZES})
-set_target_properties(cslib PROPERTIES OUTPUT_NAME lammps_cslib${LAMMPS_MACHINE})
-if(BUILD_MPI)
-  target_compile_definitions(cslib PRIVATE -DMPI_YES)
-  set_target_properties(cslib PROPERTIES OUTPUT_NAME "csmpi")
-  target_link_libraries(cslib PRIVATE MPI::MPI_CXX)
-else()
-  target_compile_definitions(cslib PRIVATE -DMPI_NO)
-  target_include_directories(cslib PRIVATE ${LAMMPS_LIB_SOURCE_DIR}/message/cslib/src/STUBS_MPI)
-  set_target_properties(cslib PROPERTIES OUTPUT_NAME "csnompi")
-endif()
-
-if(MESSAGE_ZMQ)
-  target_compile_definitions(cslib PRIVATE -DZMQ_YES)
-  find_package(ZMQ REQUIRED)
-  target_link_libraries(cslib PUBLIC ZMQ::ZMQ)
-else()
-  target_compile_definitions(cslib PRIVATE -DZMQ_NO)
-  target_include_directories(cslib PRIVATE ${LAMMPS_LIB_SOURCE_DIR}/message/cslib/src/STUBS_ZMQ)
-endif()
-
-target_link_libraries(lammps PRIVATE cslib)
-target_include_directories(lammps PRIVATE ${LAMMPS_LIB_SOURCE_DIR}/message/cslib/src)

cmake/Modules/Packages/ML-HDNNP.cmake

@@ -42,17 +42,9 @@ if(DOWNLOAD_N2P2)
   if(NOT BUILD_MPI)
     set(N2P2_PROJECT_OPTIONS "-DN2P2_NO_MPI")
   else()
-    # get path to MPI include directory when cross-compiling to windows
+    # get path to MPI include directory
-    if((CMAKE_SYSTEM_NAME STREQUAL Windows) AND CMAKE_CROSSCOMPILING)
     get_target_property(N2P2_MPI_INCLUDE MPI::MPI_CXX INTERFACE_INCLUDE_DIRECTORIES)
     set(N2P2_PROJECT_OPTIONS "-I${N2P2_MPI_INCLUDE}")
-      set(MPI_CXX_COMPILER ${CMAKE_CXX_COMPILER})
-    endif()
-    if(CMAKE_CXX_COMPILER_ID STREQUAL "Intel")
-      get_target_property(N2P2_MPI_INCLUDE MPI::MPI_CXX INTERFACE_INCLUDE_DIRECTORIES)
-      set(N2P2_PROJECT_OPTIONS "-I${N2P2_MPI_INCLUDE}")
-      set(MPI_CXX_COMPILER ${CMAKE_CXX_COMPILER})
-    endif()
   endif()
 
   # prefer GNU make, if available. N2P2 lib seems to need it.
@@ -64,8 +56,8 @@ if(DOWNLOAD_N2P2)
   string(TOUPPER "${CMAKE_BUILD_TYPE}" BTYPE)
   set(N2P2_BUILD_FLAGS "${CMAKE_SHARED_LIBRARY_CXX_FLAGS} ${CMAKE_CXX_FLAGS} ${CMAKE_CXX_FLAGS_${BTYPE}} ${N2P2_CXX_STD}")
   set(N2P2_BUILD_OPTIONS INTERFACES=LAMMPS COMP=${N2P2_COMP} "PROJECT_OPTIONS=${N2P2_PROJECT_OPTIONS}" "PROJECT_DEBUG="
-    "PROJECT_CC=${CMAKE_CXX_COMPILER}" "PROJECT_MPICC=${MPI_CXX_COMPILER}" "PROJECT_CFLAGS=${N2P2_BUILD_FLAGS}"
+    "PROJECT_CC=${CMAKE_CXX_COMPILER}" "PROJECT_MPICC=${CMAKE_CXX_COMPILER}" "PROJECT_CFLAGS=${N2P2_BUILD_FLAGS}"
-    "PROJECT_AR=${N2P2_AR}")
+    "PROJECT_AR=${N2P2_AR}" "APP_CORE=nnp-convert" "APP_TRAIN=nnp-train" "APP=nnp-convert")
   # echo final flag for debugging
   message(STATUS "N2P2 BUILD OPTIONS: ${N2P2_BUILD_OPTIONS}")
 

cmake/Modules/Packages/ML-QUIP.cmake

@@ -51,6 +51,7 @@ if(DOWNLOAD_QUIP)
     GIT_TAG origin/public
     GIT_SHALLOW YES
     GIT_PROGRESS YES
+    GIT_SUBMODULES "src/fox;src/GAP"
     PATCH_COMMAND ${CMAKE_COMMAND} -E copy_if_different ${CMAKE_BINARY_DIR}/quip.config <SOURCE_DIR>/arch/Makefile.lammps
     CONFIGURE_COMMAND env QUIP_ARCH=lammps make config
     BUILD_COMMAND env QUIP_ARCH=lammps make libquip

cmake/Modules/Packages/PHONON.cmake

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

cmake/Modules/Packages/PLUMED.cmake

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

cmake/Modules/Packages/PYTHON.cmake

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

cmake/Modules/generate_lmpgitversion.cmake

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

cmake/iwyu/iwyu-extra-map.imp

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

cmake/presets/all_off.cmake

@@ -8,6 +8,7 @@ set(ALL_PACKAGES
   AWPMD
   BOCS
   BODY
+  BPM
   BROWNIAN
   CG-DNA
   CG-SDK
@@ -48,7 +49,6 @@ set(ALL_PACKAGES
   MDI
   MEAM
   MESONT
-  MESSAGE
   MGPT
   MISC
   ML-HDNNP

cmake/presets/all_on.cmake

@@ -10,6 +10,7 @@ set(ALL_PACKAGES
   AWPMD
   BOCS
   BODY
+  BPM
   BROWNIAN
   CG-DNA
   CG-SDK
@@ -50,7 +51,6 @@ set(ALL_PACKAGES
   MDI
   MEAM
   MESONT
-  MESSAGE
   MGPT
   MISC
   ML-HDNNP

cmake/presets/gcc.cmake

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

cmake/presets/kokkos-cuda.cmake

@@ -5,7 +5,5 @@ set(PKG_KOKKOS ON CACHE BOOL "" FORCE)
 set(Kokkos_ENABLE_SERIAL ON CACHE BOOL "" FORCE)
 set(Kokkos_ENABLE_OPENMP ON CACHE BOOL "" FORCE)
 set(Kokkos_ENABLE_CUDA   ON CACHE BOOL "" FORCE)
-set(Kokkos_ARCH_MAXWELL50 on CACHE BOOL "" FORCE)
+set(Kokkos_ARCH_PASCAL60 ON CACHE BOOL "" FORCE)
 set(BUILD_OMP ON CACHE BOOL "" FORCE)
-get_filename_component(NVCC_WRAPPER_CMD ${CMAKE_CURRENT_SOURCE_DIR}/../lib/kokkos/bin/nvcc_wrapper ABSOLUTE)
-set(CMAKE_CXX_COMPILER ${NVCC_WRAPPER_CMD} CACHE FILEPATH "" FORCE)

cmake/presets/kokkos-sycl.cmake

@@ -0,0 +1,15 @@
+# preset that enables KOKKOS and selects SYCL compilation with OpenMP
+# enabled as well. Also sets some performance related compiler flags.
+set(PKG_KOKKOS ON CACHE BOOL "" FORCE)
+set(Kokkos_ENABLE_SERIAL ON CACHE BOOL "" FORCE)
+set(Kokkos_ENABLE_OPENMP ON CACHE BOOL "" FORCE)
+set(Kokkos_ENABLE_CUDA   OFF CACHE BOOL "" FORCE)
+set(Kokkos_ENABLE_SYCL   ON CACHE BOOL "" FORCE)
+set(Kokkos_ARCH_MAXWELL50 on CACHE BOOL "" FORCE)
+set(BUILD_OMP ON CACHE BOOL "" FORCE)
+
+set(CMAKE_CXX_COMPILER clang++ CACHE STRING "" FORCE)
+set(MPI_CXX_COMPILER "mpicxx" CACHE STRING "" FORCE)
+set(CMAKE_CXX_STANDARD 17 CACHE STRING "" FORCE)
+set(CMAKE_SHARED_LINKER_FLAGS "-Xsycl-target-frontend -O3" CACHE STRING "" FORCE)
+set(CMAKE_TUNE_FLAGS "-fgpu-inline-threshold=100000 -Xsycl-target-frontend -O3  -Xsycl-target-frontend -ffp-contract=on -Wno-unknown-cuda-version" CACHE STRING "" FORCE)

cmake/presets/mingw-cross.cmake

@@ -4,6 +4,7 @@ set(WIN_PACKAGES
   AWPMD
   BOCS
   BODY
+  BPM
   BROWNIAN
   CG-DNA
   CG-SDK

cmake/presets/most.cmake

@@ -6,6 +6,7 @@ set(ALL_PACKAGES
   ASPHERE
   BOCS
   BODY
+  BPM
   BROWNIAN
   CG-DNA
   CG-SDK

cmake/presets/nolib.cmake

@@ -15,7 +15,6 @@ set(PACKAGES_WITH_LIB
   MACHDYN
   MDI
   MESONT
-  MESSAGE
   ML-HDNNP
   ML-PACE
   ML-QUIP

cmake/presets/pgi.cmake

@@ -1,4 +1,4 @@
-# preset that will enable clang/clang++ with support for MPI and OpenMP (on Linux boxes)
+# preset that will enable PGI (Nvidia) compilers with support for MPI and OpenMP (on Linux boxes)
 
 set(CMAKE_CXX_COMPILER "pgc++" CACHE STRING "" FORCE)
 set(CMAKE_C_COMPILER "pgcc" CACHE STRING "" FORCE)

cmake/presets/windows.cmake

@@ -2,6 +2,7 @@ set(WIN_PACKAGES
   ASPHERE
   BOCS
   BODY
+  BPM
   BROWNIAN
   CG-DNA
   CG-SDK

doc/.gitignore

@@ -1,6 +1,6 @@
 /old
 /html
-/html-offline
+/fasthtml
 /epub
 /latex
 /mathjax

doc/Makefile

@@ -14,34 +14,22 @@ ANCHORCHECK    = $(VENV)/bin/rst_anchor_check
 SPHINXCONFIG   = $(BUILDDIR)/utils/sphinx-config
 MATHJAX        = $(SPHINXCONFIG)/_static/mathjax
 
-PYTHON         = $(shell which python3)
+PYTHON         = $(word 3,$(shell type python3))
-DOXYGEN        = $(shell which doxygen)
+DOXYGEN        = $(word 3,$(shell type doxygen))
-VIRTUALENV     = virtualenv
 HAS_PYTHON3    = NO
-HAS_VIRTUALENV = NO
 HAS_DOXYGEN    = NO
 HAS_PDFLATEX   = NO
 
-ifeq ($(shell which python3 >/dev/null 2>&1; echo $$?), 0)
+ifeq ($(shell type python3 >/dev/null 2>&1; echo $$?), 0)
 HAS_PYTHON3    = YES
 endif
 
-ifeq ($(shell which doxygen >/dev/null 2>&1; echo $$?), 0)
+ifeq ($(shell type doxygen >/dev/null 2>&1; echo $$?), 0)
 HAS_DOXYGEN    = YES
 endif
 
-ifeq ($(shell which virtualenv-3 >/dev/null 2>&1; echo $$?), 0)
+ifeq ($(shell type pdflatex >/dev/null 2>&1; echo $$?), 0)
-VIRTUALENV     = virtualenv-3
+ifeq ($(shell type latexmk >/dev/null 2>&1; echo $$?), 0)
-HAS_VIRTUALENV = YES
-endif
-
-ifeq ($(shell which virtualenv >/dev/null 2>&1; echo $$?), 0)
-VIRTUALENV     = virtualenv
-HAS_VIRTUALENV = YES
-endif
-
-ifeq ($(shell which pdflatex >/dev/null 2>&1; echo $$?), 0)
-ifeq ($(shell which latexmk >/dev/null 2>&1; echo $$?), 0)
 HAS_PDFLATEX = YES
 endif
 endif
@@ -58,7 +46,7 @@ SPHINXEXTRA = -E -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiproc
 # 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
+.PHONY: help clean-all clean clean-spelling epub mobi rst html pdf spelling anchor_check style_check char_check xmlgen fasthtml
 
 # ------------------------------------------
 
@@ -70,7 +58,8 @@ help:
 	@echo "  epub          create ePUB format manual for e-book readers"
 	@echo "  mobi          convert ePUB to MOBI format manual for e-book readers (e.g. Kindle)"
 	@echo "                      (requires ebook-convert tool from calibre)"
-	@echo "  clean         remove all intermediate RST files"
+	@echo "  fasthtml      approximate HTML page creation in fasthtml dir (for development)"
+	@echo "  clean         remove all intermediate files"
 	@echo "  clean-all     reset the entire build environment"
 	@echo "  anchor_check  scan for duplicate anchor labels"
 	@echo "  style_check   check for complete and consistent style lists"
@@ -83,7 +72,7 @@ clean-all: clean
 	rm -rf $(BUILDDIR)/docenv $(MATHJAX) $(BUILDDIR)/LAMMPS.mobi $(BUILDDIR)/LAMMPS.epub $(BUILDDIR)/Manual.pdf
 
 clean: clean-spelling
-	rm -rf $(BUILDDIR)/html $(BUILDDIR)/epub $(BUILDDIR)/latex $(BUILDDIR)/doctrees $(BUILDDIR)/doxygen/xml $(BUILDDIR)/doxygen-warn.log $(BUILDDIR)/doxygen/Doxyfile $(SPHINXCONFIG)/conf.py
+	rm -rf $(BUILDDIR)/html $(BUILDDIR)/epub $(BUILDDIR)/latex $(BUILDDIR)/doctrees $(BUILDDIR)/doxygen/xml $(BUILDDIR)/doxygen-warn.log $(BUILDDIR)/doxygen/Doxyfile $(SPHINXCONFIG)/conf.py $(BUILDDIR)/fasthtml
 
 clean-spelling:
 	rm -rf $(BUILDDIR)/spelling
@@ -118,6 +107,23 @@ html: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX)
 	@rm -rf html/PDF/.[sg]*
 	@echo "Build finished. The HTML pages are in doc/html."
 
+fasthtml: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX)
+	@if [ "$(HAS_BASH)" == "NO" ] ; then echo "bash was not found at $(OSHELL)! Please use: $(MAKE) SHELL=/path/to/bash" 1>&2; exit 1; fi
+	@$(MAKE) $(MFLAGS) -C graphviz all
+	@mkdir -p fasthtml
+	@(\
+		. $(VENV)/bin/activate ; env PYTHONWARNINGS= \
+		sphinx-build -j 4 -b html -c $(SPHINXCONFIG) -d $(BUILDDIR)/fasthtml/doctrees $(RSTDIR) fasthtml ;\
+		deactivate ;\
+	)
+	@rm -rf fasthtml/_sources
+	@rm -rf fasthtml/PDF
+	@rm -rf fasthtml/USER
+	@rm -rf fasthtml/JPG
+	@cp -r src/PDF fasthtml/PDF
+	@rm -rf fasthtml/PDF/.[sg]*
+	@echo "Fast HTML build finished. The HTML pages are in doc/fasthtml."
+
 spelling: xmlgen $(SPHINXCONFIG)/conf.py $(VENV) $(SPHINXCONFIG)/false_positives.txt
 	@if [ "$(HAS_BASH)" == "NO" ] ; then echo "bash was not found at $(OSHELL)! Please use: $(MAKE) SHELL=/path/to/bash" 1>&2; exit 1; fi
 	@(\
@@ -220,9 +226,8 @@ $(VENV):
 	@if [ "$(HAS_BASH)" == "NO" ] ; then echo "bash was not found at $(OSHELL)! Please use: $(MAKE) SHELL=/path/to/bash" 1>&2; exit 1; fi
 	@if [ "$(HAS_PYTHON3)" == "NO" ] ; then echo "python3 was not found! Please see README for further instructions" 1>&2; exit 1; fi
 	@if [ "$(HAS_DOXYGEN)" == "NO" ] ; then echo "doxygen was not found! Please see README for further instructions" 1>&2; exit 1; fi
-	@if [ "$(HAS_VIRTUALENV)" == "NO" ] ; then echo "virtualenv was not found! Please see README for further instructions" 1>&2; exit 1; fi
 	@( \
-		$(VIRTUALENV) -p $(PYTHON) $(VENV); \
+		$(PYTHON) -m venv $(VENV); \
 		. $(VENV)/bin/activate; \
 		pip $(PIP_OPTIONS) install --upgrade pip; \
 		pip $(PIP_OPTIONS) install -r $(BUILDDIR)/utils/requirements.txt; \

doc/lammps.1

@@ -1,7 +1,7 @@
-.TH LAMMPS "1" "27 October 2021" "2021-10-27"
+.TH LAMMPS "1" "24 March 2022" "2022-3-24"
 .SH NAME
 .B LAMMPS
-\- Molecular Dynamics Simulator.
+\- Molecular Dynamics Simulator.  Version 24 March 2022
 
 .SH SYNOPSIS
 .B lmp
@@ -297,7 +297,7 @@ the chapter on errors in the
 manual gives some additional information about error messages, if possible.
 
 .SH COPYRIGHT
-© 2003--2021 Sandia Corporation
+© 2003--2022 Sandia Corporation
 
 This package is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License version 2 as

doc/msi2lmp.1

@@ -98,7 +98,7 @@ msi2lmp decane -c 0 -f oplsaa
 
 
 .SH COPYRIGHT
-© 2003--2021 Sandia Corporation
+© 2003--2022 Sandia Corporation
 
 This package is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License version 2 as

doc/src/Bibliography.rst

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

doc/src/Build_development.rst

@@ -185,6 +185,10 @@ The ``ctest`` command has many options, the most important ones are:
      - run subset of tests matching the regular expression <regex>
    * - -E <regex>
      - exclude subset of tests matching the regular expression <regex>
+   * - -L <regex>
+     - run subset of tests with a label matching the regular expression <regex>
+   * - -LE <regex>
+     - exclude subset of tests with a label matching the regular expression <regex>
    * - -N
      - dry-run: display list of tests without running them
    * - -T memcheck
@@ -299,6 +303,12 @@ will destroy the original file, if the generation run does not complete,
 so using *-g* is recommended unless the YAML file is fully tested
 and working.
 
+Some of the force style tests are rather slow to run and some are very
+sensitive to small differences like CPU architecture, compiler
+toolchain, compiler optimization. Those tests are flagged with a "slow"
+and/or "unstable" label, and thus those tests can be selectively
+excluded with the ``-LE`` flag or selected with the ``-L`` flag.
+
 .. admonition:: Recommendations and notes for YAML files
    :class: note
 
@@ -476,14 +486,14 @@ The following options are available.
    make fix-whitespace      # correct whitespace issues in files
    make check-homepage      # search for files with old LAMMPS homepage URLs
    make fix-homepage        # correct LAMMPS homepage URLs in files
+   make check-errordocs     # search for deprecated error docs in header files
+   make fix-errordocs       # remove error docs in header files
    make check-permissions   # search for files with permissions issues
    make fix-permissions     # correct permissions issues in files
+   make check               # run all check targets from above
 
-These should help to replace all TAB characters with blanks and remove
+These should help to make source and documentation files conforming
-any trailing whitespace.  Also all LAMMPS homepage URL references can be
+to some the coding style preferences of the LAMMPS developers.
-updated to the location change from Sandia to the lammps.org domain.
-And the permission check can remove executable permissions from non-executable
-files (like source code).
 
 Clang-format support
 --------------------

doc/src/Build_extras.rst

@@ -45,7 +45,6 @@ This is the list of packages that may require additional steps.
    * :ref:`MACHDYN <machdyn>`
    * :ref:`MDI <mdi>`
    * :ref:`MESONT <mesont>`
-   * :ref:`MESSAGE <message>`
    * :ref:`ML-HDNNP <ml-hdnnp>`
    * :ref:`ML-IAP <mliap>`
    * :ref:`ML-PACE <ml-pace>`
@@ -142,8 +141,6 @@ CMake build
 
 :code:`GPU_ARCH` settings for different GPU hardware is as follows:
 
-* sm_12 or sm_13 for GT200 (supported by CUDA 3.2 until CUDA 6.5)
-* sm_20 or sm_21 for Fermi (supported by CUDA 3.2 until CUDA 7.5)
 * sm_30 for Kepler (supported since CUDA 5 and until CUDA 10.x)
 * sm_35 or sm_37 for Kepler (supported since CUDA 5 and until CUDA 11.x)
 * sm_50 or sm_52 for Maxwell (supported since CUDA 6)
@@ -161,6 +158,12 @@ Thus the GPU_ARCH setting is merely an optimization, to have code for
 the preferred GPU architecture directly included rather than having to wait
 for the JIT compiler of the CUDA driver to translate it.
 
+When compiling for CUDA or HIP with CUDA, version 8.0 or later of the CUDA toolkit
+is required and a GPU architecture of Kepler or later, which must *also* be
+supported by the CUDA toolkit in use **and** the CUDA driver in use.
+When compiling for OpenCL, OpenCL version 1.2 or later is required and the
+GPU must be supported by the GPU driver and OpenCL runtime bundled with the driver.
+
 When building with CMake, you **must NOT** build the GPU library in ``lib/gpu``
 using the traditional build procedure. CMake will detect files generated by that
 process and will terminate with an error and a suggestion for how to remove them.
@@ -341,6 +344,18 @@ minutes to hours) to build.  Of course you only need to do that once.)
          $ make lib-kim args="-p /usr/local" # use an existing KIM API installation at the provided location
          $ make lib-kim args="-p /usr/local -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # ditto but add one model or driver
 
+      When using the "-b " option, the KIM library is built using its native
+      cmake build system.  The ``lib/kim/Install.py`` script supports a
+      ``CMAKE`` environment variable if the cmake executable is named other
+      than ``cmake`` on your system.  Additional environment variables may be
+      provided on the command line for use by cmake.  For example, to use the
+      ``cmake3`` executable and tell it to use the gnu version 11 compilers
+      to build KIM, one could use the following command line.
+
+      .. code-block:: bash
+
+         $ CMAKE=cmake3 CXX=g++-11 CC=gcc-11 FC=gfortran-11 make lib-kim args="-b "  # (re-)install KIM API lib using cmake3 and gnu v11 compilers with only example models
+
       Settings for debugging OpenKIM web queries discussed below need to
       be applied by adding them to the ``LMP_INC`` variable through
       editing the ``Makefile.machine`` you are using.  For example:
@@ -560,11 +575,26 @@ They must be specified in uppercase.
    *  - VEGA908
       - GPU
       - AMD GPU MI100 GFX908
-   *  - INTEL_GEN
+   *  - VEGA90A
       - GPU
-      - Intel GPUs Gen9+
+      - AMD GPU
+   *  - INTEL_DG1
+      - GPU
+      - Intel Iris XeMAX GPU
+   *  - INTEL_GEN9
+      - GPU
+      - Intel GPU Gen9
+   *  - INTEL_GEN11
+      - GPU
+      - Intel GPU Gen11
+   *  - INTEL_GEN12LP
+      - GPU
+      - Intel GPU Gen12LP
+   *  - INTEL_XEHP
+      - GPU
+      - Intel GPUs Xe-HP
 
-This list was last updated for version 3.4.1 of the Kokkos library.
+This list was last updated for version 3.5.0 of the Kokkos library.
 
 .. tabs::
 
@@ -611,13 +641,14 @@ This list was last updated for version 3.4.1 of the Kokkos library.
 
          -D CMAKE_CXX_COMPILER=${HOME}/lammps/lib/kokkos/bin/nvcc_wrapper
 
-      To simplify compilation, three preset files are included in the
+      To simplify compilation, four preset files are included in the
       ``cmake/presets`` folder, ``kokkos-serial.cmake``,
-      ``kokkos-openmp.cmake``, and ``kokkos-cuda.cmake``. They will
+      ``kokkos-openmp.cmake``, ``kokkos-cuda.cmake``, and
-      enable the KOKKOS package and enable some hardware choice.  So to
+      ``kokkos-sycl.cmake``.  They will enable the KOKKOS package and
-      compile with OpenMP host parallelization, CUDA device
+      enable some hardware choice.  So to compile with OpenMP host
-      parallelization (for GPUs with CC 5.0 and up) with some common
+      parallelization, CUDA device parallelization (for GPUs with CC 5.0
-      packages enabled, you can do the following:
+      and up) with some common packages enabled, you can do the
+      following:
 
       .. code-block:: bash
 
@@ -769,47 +800,6 @@ library.
 
 ----------
 
-.. _message:
-
-MESSAGE package
------------------------------
-
-This package can optionally include support for messaging via sockets,
-using the open-source `ZeroMQ library <http://zeromq.org>`_, which must
-be installed on your system.
-
-.. tabs::
-
-   .. tab:: CMake build
-
-      .. code-block:: bash
-
-         -D MESSAGE_ZMQ=value    # build with ZeroMQ support, value = no (default) or yes
-         -D ZMQ_LIBRARY=path     # ZMQ library file (only needed if a custom location)
-         -D ZMQ_INCLUDE_DIR=path # ZMQ include directory (only needed if a custom location)
-
-   .. tab:: Traditional make
-
-      Before building LAMMPS, you must build the CSlib library in
-      ``lib/message``\ .  You can build the CSlib library manually if
-      you prefer; follow the instructions in ``lib/message/README``\ .
-      You can also do it in one step from the ``lammps/src`` dir, using
-      a command like these, which simply invoke the
-      ``lib/message/Install.py`` script with the specified args:
-
-      .. code-block:: bash
-
-         $ make lib-message               # print help message
-         $ make lib-message args="-m -z"  # build with MPI and socket (ZMQ) support
-         $ make lib-message args="-s"     # build as serial lib with no ZMQ support
-
-      The build should produce two files: ``lib/message/cslib/src/libmessage.a``
-      and ``lib/message/Makefile.lammps``.  The latter is copied from an
-      existing ``Makefile.lammps.*`` and has settings to link with the ZeroMQ
-      library if requested in the build.
-
-----------
-
 .. _mliap:
 
 ML-IAP package

doc/src/Build_manual.rst

@@ -78,11 +78,12 @@ folder.  The following ``make`` commands are available:
 
    make html          # generate HTML in html dir using Sphinx
    make pdf           # generate PDF  as Manual.pdf using Sphinx and PDFLaTeX
-   make fetch         # fetch HTML pages and PDF files from LAMMPS website
-                      #  and unpack into the html_www folder and Manual_www.pdf
    make epub          # generate LAMMPS.epub in ePUB format using Sphinx
    make mobi          # generate LAMMPS.mobi in MOBI format using ebook-convert
 
+   make fasthtml      # generate approximate HTML in fasthtml dir using Sphinx
+                      # some Sphinx extensions do not work correctly with this
+
    make clean         # remove intermediate RST files created by HTML build
    make clean-all     # remove entire build folder and any cached data
 
@@ -193,8 +194,13 @@ folder need to be updated or new files added. These files are written in
 `reStructuredText <rst_>`_ markup for translation with the Sphinx tool.
 
 Before contributing any documentation, please check that both the HTML
-and the PDF format documentation can translate without errors. Please also
+and the PDF format documentation can translate without errors.  During
-check the output to the console for any warnings or problems.  There will
+testing the html translation, you may use the ``make fasthtml`` command
+which does an approximate translation (i.e. not all Sphinx features and
+extensions will work), but runs very fast because it will only translate
+files that have been changed since the last ``make fasthtml`` command.
+
+Please also check the output to the console for any warnings or problems.  There will
 be multiple tests run automatically:
 
 - A test for correctness of all anchor labels and their references

doc/src/Build_package.rst

@@ -45,7 +45,6 @@ packages:
    * :ref:`KOKKOS <kokkos>`
    * :ref:`LATTE <latte>`
    * :ref:`MACHDYN <machdyn>`
-   * :ref:`MESSAGE <message>`
    * :ref:`ML-HDNNP <ml-hdnnp>`
    * :ref:`ML-PACE <ml-pace>`
    * :ref:`ML-QUIP <ml-quip>`

doc/src/Build_settings.rst

@@ -4,15 +4,15 @@ Optional build settings
 LAMMPS can be built with several optional settings.  Each sub-section
 explain how to do this for building both with CMake and make.
 
-* :ref:`C++11 standard compliance <cxx11>` when building all of LAMMPS
+* `C++11 standard compliance`_ when building all of LAMMPS
-* :ref:`FFT library <fft>` for use with the :doc:`kspace_style pppm <kspace_style>` command
+* `FFT library`_ for use with the :doc:`kspace_style pppm <kspace_style>` command
-* :ref:`Size of LAMMPS integer types <size>`
+* `Size of LAMMPS integer types and size limits`_
-* :ref:`Read or write compressed files <gzip>`
+* `Read or write compressed files`_
-* :ref:`Output of JPG and PNG files <graphics>` via the :doc:`dump image <dump_image>` command
+* `Output of JPG, PNG, and move files` via the :doc:`dump image <dump_image>` or :doc:`dump movie <dump_image>` commands
-* :ref:`Output of movie files <graphics>` via the :doc:`dump_movie <dump_image>` command
+* `Memory allocation alignment`_
-* :ref:`Memory allocation alignment <align>`
+* `Workaround for long long integers`_
-* :ref:`Workaround for long long integers <longlong>`
+* `Exception handling when using LAMMPS as a library`_ to capture errors
-* :ref:`Error handling exceptions <exceptions>` when using LAMMPS as a library
+* `Trigger selected floating-point exceptions`_
 
 ----------
 

doc/src/Build_windows.rst

@@ -16,44 +16,52 @@ General remarks
 
 LAMMPS is developed and tested primarily on Linux machines.  The vast
 majority of HPC clusters and supercomputers today run on Linux as well.
-While portability to other platforms is desired, it is not always achieved.
+While portability to other platforms is desired, it is not always
-The LAMMPS developers are dependent on LAMMPS users giving feedback and
+achieved.  That is sometimes due to non-portable code in LAMMPS itself,
-providing assistance in resolving portability issues.  This is particularly
+but more often due to portability limitations of external libraries and
-true for compiling LAMMPS on Windows, since this platform has significant
+tools required to build a specific feature or package.  The LAMMPS
-differences in some low-level functionality.
+developers are dependent on LAMMPS users giving feedback and providing
+assistance in resolving portability issues.  This is particularly true
+for compiling LAMMPS on Windows, since this platform has significant
+differences in some low-level functionality.  As of LAMMPS version 14
+December 2021, large parts of LAMMPS can be compiled natively with the
+Microsoft Visual C++ Compilers.  This is largely facilitated by using
+the :doc:`Developer_platform` in the ``platform`` namespace.
+
+Before trying to build LAMMPS on Windows yourself, please consider the
+`pre-compiled Windows installer packages <https://packages.lammps.org/windows.html>`_
+and see if they are sufficient for your needs.
 
 .. _linux:
 
 Running Linux on Windows
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-Before trying to build LAMMPS on Windows, please consider if the
+If it is necessary for you to compile LAMMPS on a Windows machine
-pre-compiled Windows binary packages are sufficient for your needs.  If
-it is necessary for you to compile LAMMPS on a Windows machine
 (e.g. because it is your main desktop), please also consider using a
 virtual machine software and compile and run LAMMPS in a Linux virtual
 machine, or - if you have a sufficiently up-to-date Windows 10 or
 Windows 11 installation - consider using the Windows subsystem for
 Linux.  This optional Windows feature allows you to run the bash shell
-from Ubuntu from within Windows and from there on, you can pretty much
+of a Linux system (Ubuntu by default) from within Windows and from there
-use that shell like you are running on an Ubuntu Linux machine
+on, you can pretty much use that shell like you are running on a regular
-(e.g. installing software via apt-get and more).  For more details on
+Ubuntu Linux machine (e.g. installing software via apt-get and more).
-that, please see :doc:`this tutorial <Howto_wsl>`.
+For more details on that, please see :doc:`this tutorial <Howto_wsl>`.
 
 .. _gnu:
 
 Using a GNU GCC ported to Windows
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-One option for compiling LAMMPS on Windows natively that has been known
+One option for compiling LAMMPS on Windows natively is to install a Bash
-to work in the past is to install a bash shell, unix shell utilities,
+shell, Unix shell utilities, Perl, Python, GNU make, and a GNU compiler
-perl, GNU make, and a GNU compiler ported to Windows.  The Cygwin
+ported to Windows.  The Cygwin package provides a unix/linux interface
-package provides a unix/linux interface to low-level Windows functions,
+to low-level Windows functions, so LAMMPS can be compiled on Windows.
-so LAMMPS can be compiled on Windows.  The necessary (minor)
+The necessary (minor) modifications to LAMMPS are included, but may not
-modifications to LAMMPS are included, but may not always up-to-date for
+always up-to-date for recently added functionality and the corresponding
-recently added functionality and the corresponding new code.  A machine
+new code.  A machine makefile for using cygwin for the old build system
-makefile for using cygwin for the old build system is provided. Using
+is provided.  Using CMake for this mode of compilation is untested and
-CMake for this mode of compilation is untested and not likely to work.
+not likely to work.
 
 When compiling for Windows do **not** set the ``-DLAMMPS_MEMALIGN``
 define in the LMP_INC makefile variable and add ``-lwsock32 -lpsapi`` to
@@ -65,8 +73,9 @@ configuration should set this up automatically, but is untested.
 In case of problems, you are recommended to contact somebody with
 experience in using Cygwin.  If you do come across portability problems
 requiring changes to the LAMMPS source code, or figure out corrections
-yourself, please report them on the lammps-users mailing list, or file
+yourself, please report them on the
-them as an issue or pull request on the LAMMPS GitHub project.
+`LAMMPS forum at MatSci <https://matsci.org/c/lammps/lammps-development/>`_,
+or file them as an issue or pull request on the LAMMPS GitHub project.
 
 .. _msvc:
 
@@ -75,19 +84,27 @@ Using Microsoft Visual Studio
 
 Following the integration of the :doc:`platform namespace
 <Developer_platform>` into the LAMMPS code base, portability of LAMMPS
-to be compiled on Windows using Visual Studio has been significantly
+for native compilation on Windows using Visual Studio has been
-improved.  This has been tested with Visual Studio 2019 (aka version
+significantly improved.  This has been tested with Visual Studio 2019
-16).  Not all features and packages in LAMMPS are currently supported
+(aka version 16) and Visual Studio 2022 (aka version 17).  We strongly
-out of the box, but a preset ``cmake/presets/windows.cmake`` is provided
+recommend using Visual Studio 2022 version 17.1 or later.  Not all
-that contains the packages that have been compiled successfully.  You
+features and packages in LAMMPS are currently supported out of the box,
-must use the CMake based build procedure, and either use the integrated
+but a preset ``cmake/presets/windows.cmake`` is provided that contains
-CMake support of Visual Studio or use an external CMake installation to
+the packages that have been compiled successfully so far.  You **must**
-create build files for the Visual Studio build system.  Please note that
+use the CMake based build procedure, since there is no support for GNU
-on launching Visual Studio it will scan the directory tree and likely
+make or the Unix shell utilities required for the GNU make build
-miss the correct master ``CMakeLists.txt``.  Try to open the
+procedure.
-``cmake/CMakeSettings.json`` and use those CMake configurations as a
+
-starting point.  It is also possible to configure and compile LAMMPS
+It is possible to use both the integrated CMake support of the Visual
-from the command line with a CMake binary from `cmake.org <https://cmake.org>`_.
+Studio IDE or use an external CMake installation (e.g. downloaded from
+cmake.org) to create build files and compile LAMMPS from the command line.
+
+.. note::
+
+   Versions of Visual Studio before version 17.1 may scan the entire
+   LAMMPS source tree and likely miss the correct master
+   ``CMakeLists.txt`` and get confused since there are multiple files
+   of that name in different folders but none in top level folder.
 
 Please note, that for either approach CMake will create a so-called
 :ref:`"multi-configuration" build environment <cmake_multiconfig>`, and
@@ -98,9 +115,11 @@ To support running in parallel you can compile with OpenMP enabled using
 the OPENMP package or install Microsoft MPI (including the SDK) and compile
 LAMMPS with MPI enabled.
 
-This is work in progress and you should contact the LAMMPS developers
+.. note::
-via GitHub, the forum, or the mailing list, if you have questions or
+
-LAMMPS specific problems.
+   This is work in progress and you should contact the LAMMPS developers
+   via GitHub or the `LAMMPS forum at MatSci <https://matsci.org/c/lammps/lammps-development/>`_,
+   if you have questions or LAMMPS specific problems.
 
 .. _cross:
 

doc/src/Commands_all.rst

@@ -47,7 +47,7 @@ An alphabetic list of all general LAMMPS commands.
    * :doc:`displace_atoms <displace_atoms>`
    * :doc:`dump <dump>`
    * :doc:`dump_modify <dump_modify>`
-   * :doc:`dynamical_matrix <dynamical_matrix>`
+   * :doc:`dynamical_matrix (k) <dynamical_matrix>`
    * :doc:`echo <echo>`
    * :doc:`fix <fix>`
    * :doc:`fix_modify <fix_modify>`
@@ -67,8 +67,7 @@ An alphabetic list of all general LAMMPS commands.
    * :doc:`lattice <lattice>`
    * :doc:`log <log>`
    * :doc:`mass <mass>`
-   * :doc:`mdi/engine <mdi_engine>`
+   * :doc:`mdi <mdi>`
-   * :doc:`message <message>`
    * :doc:`minimize <minimize>`
    * :doc:`min_modify <min_modify>`
    * :doc:`min_style <min_style>`
@@ -105,7 +104,6 @@ An alphabetic list of all general LAMMPS commands.
    * :doc:`restart <restart>`
    * :doc:`run <run>`
    * :doc:`run_style <run_style>`
-   * :doc:`server <server>`
    * :doc:`set <set>`
    * :doc:`shell <shell>`
    * :doc:`special_bonds <special_bonds>`
@@ -117,7 +115,7 @@ An alphabetic list of all general LAMMPS commands.
    * :doc:`thermo <thermo>`
    * :doc:`thermo_modify <thermo_modify>`
    * :doc:`thermo_style <thermo_style>`
-   * :doc:`third_order <third_order>`
+   * :doc:`third_order (k) <third_order>`
    * :doc:`timer <timer>`
    * :doc:`timestep <timestep>`
    * :doc:`uncompute <uncompute>`

doc/src/Commands_bond.rst

@@ -32,9 +32,12 @@ OPT.
    *
    *
    *
+   * :doc:`bpm/rotational <bond_bpm_rotational>`
+   * :doc:`bpm/spring <bond_bpm_spring>`
    * :doc:`class2 (ko) <bond_class2>`
    * :doc:`fene (iko) <bond_fene>`
    * :doc:`fene/expand (o) <bond_fene_expand>`
+   * :doc:`fene/nm <bond_fene>`
    * :doc:`gaussian <bond_gaussian>`
    * :doc:`gromos (o) <bond_gromos>`
    * :doc:`harmonic (iko) <bond_harmonic>`

doc/src/Commands_compute.rst

@@ -28,10 +28,12 @@ KOKKOS, o = OPENMP, t = OPT.
    * :doc:`angle <compute_angle>`
    * :doc:`angle/local <compute_angle_local>`
    * :doc:`angmom/chunk <compute_angmom_chunk>`
+   * :doc:`ave/sphere/atom (k) <compute_ave_sphere_atom>`
    * :doc:`basal/atom <compute_basal_atom>`
    * :doc:`body/local <compute_body_local>`
    * :doc:`bond <compute_bond>`
    * :doc:`bond/local <compute_bond_local>`
+   * :doc:`born/matrix <compute_born_matrix>`
    * :doc:`centro/atom <compute_centro_atom>`
    * :doc:`centroid/stress/atom <compute_stress_atom>`
    * :doc:`chunk/atom <compute_chunk_atom>`
@@ -62,6 +64,7 @@ KOKKOS, o = OPENMP, t = OPT.
    * :doc:`event/displace <compute_event_displace>`
    * :doc:`fabric <compute_fabric>`
    * :doc:`fep <compute_fep>`
+   * :doc:`fep/ta <compute_fep_ta>`
    * :doc:`force/tally <compute_tally>`
    * :doc:`fragment/atom <compute_cluster_atom>`
    * :doc:`global/atom <compute_global_atom>`
@@ -89,6 +92,7 @@ KOKKOS, o = OPENMP, t = OPT.
    * :doc:`msd <compute_msd>`
    * :doc:`msd/chunk <compute_msd_chunk>`
    * :doc:`msd/nongauss <compute_msd_nongauss>`
+   * :doc:`nbond/atom <compute_nbond_atom>`
    * :doc:`omega/chunk <compute_omega_chunk>`
    * :doc:`orientorder/atom (k) <compute_orientorder_atom>`
    * :doc:`pair <compute_pair>`
@@ -99,7 +103,6 @@ KOKKOS, o = OPENMP, t = OPT.
    * :doc:`pe/tally <compute_tally>`
    * :doc:`plasticity/atom <compute_plasticity_atom>`
    * :doc:`pressure <compute_pressure>`
-   * :doc:`pressure/cylinder <compute_pressure_cylinder>`
    * :doc:`pressure/uef <compute_pressure_uef>`
    * :doc:`property/atom <compute_property_atom>`
    * :doc:`property/chunk <compute_property_chunk>`
@@ -142,8 +145,11 @@ KOKKOS, o = OPENMP, t = OPT.
    * :doc:`sph/t/atom <compute_sph_t_atom>`
    * :doc:`spin <compute_spin>`
    * :doc:`stress/atom <compute_stress_atom>`
+   * :doc:`stress/cartesian <compute_stress_profile>`
+   * :doc:`stress/cylinder <compute_stress_profile>`
    * :doc:`stress/mop <compute_stress_mop>`
    * :doc:`stress/mop/profile <compute_stress_mop>`
+   * :doc:`stress/spherical <compute_stress_profile>`
    * :doc:`stress/tally <compute_tally>`
    * :doc:`tdpd/cc/atom <compute_tdpd_cc_atom>`
    * :doc:`temp (k) <compute_temp>`

doc/src/Commands_fix.rst

@@ -51,10 +51,10 @@ OPT.
    * :doc:`bond/swap <fix_bond_swap>`
    * :doc:`box/relax <fix_box_relax>`
    * :doc:`charge/regulation <fix_charge_regulation>`
-   * :doc:`client/md <fix_client_md>`
    * :doc:`cmap <fix_cmap>`
    * :doc:`colvars <fix_colvars>`
    * :doc:`controller <fix_controller>`
+   * :doc:`damping/cundall <fix_damping_cundall>`
    * :doc:`deform (k) <fix_deform>`
    * :doc:`deposit <fix_deposit>`
    * :doc:`dpd/energy (k) <fix_dpd_energy>`
@@ -97,12 +97,10 @@ OPT.
    * :doc:`latte <fix_latte>`
    * :doc:`lb/fluid <fix_lb_fluid>`
    * :doc:`lb/momentum <fix_lb_momentum>`
-   * :doc:`lb/pc <fix_lb_pc>`
-   * :doc:`lb/rigid/pc/sphere <fix_lb_rigid_pc_sphere>`
    * :doc:`lb/viscous <fix_lb_viscous>`
    * :doc:`lineforce <fix_lineforce>`
    * :doc:`manifoldforce <fix_manifoldforce>`
-   * :doc:`mdi/engine <fix_mdi_engine>`
+   * :doc:`mdi/aimd <fix_mdi_aimd>`
    * :doc:`meso/move <fix_meso_move>`
    * :doc:`mol/swap <fix_mol_swap>`
    * :doc:`momentum (k) <fix_momentum>`
@@ -129,6 +127,7 @@ OPT.
    * :doc:`npt/sphere (o) <fix_npt_sphere>`
    * :doc:`npt/uef <fix_nh_uef>`
    * :doc:`numdiff <fix_numdiff>`
+   * :doc:`numdiff/virial <fix_numdiff_virial>`
    * :doc:`nve (giko) <fix_nve>`
    * :doc:`nve/asphere (gi) <fix_nve_asphere>`
    * :doc:`nve/asphere/noforce <fix_nve_asphere_noforce>`
@@ -142,6 +141,7 @@ OPT.
    * :doc:`nve/manifold/rattle <fix_nve_manifold_rattle>`
    * :doc:`nve/noforce <fix_nve_noforce>`
    * :doc:`nve/sphere (ko) <fix_nve_sphere>`
+   * :doc:`nve/bpm/sphere <fix_nve_bpm_sphere>`
    * :doc:`nve/spin <fix_nve_spin>`
    * :doc:`nve/tri <fix_nve_tri>`
    * :doc:`nvk <fix_nvk>`
@@ -159,7 +159,6 @@ OPT.
    * :doc:`orient/fcc <fix_orient>`
    * :doc:`orient/eco <fix_orient_eco>`
    * :doc:`pafi <fix_pafi>`
-   * :doc:`pair/tracker <fix_pair_tracker>`
    * :doc:`phonon <fix_phonon>`
    * :doc:`pimd <fix_pimd>`
    * :doc:`planeforce <fix_planeforce>`
@@ -244,6 +243,7 @@ OPT.
    * :doc:`vector <fix_vector>`
    * :doc:`viscosity <fix_viscosity>`
    * :doc:`viscous <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:`wall/colloid <fix_wall>`

doc/src/Commands_pair.rst

@@ -53,6 +53,7 @@ OPT.
    * :doc:`born/coul/msm (o) <pair_born>`
    * :doc:`born/coul/wolf (go) <pair_born>`
    * :doc:`born/coul/wolf/cs (g) <pair_cs>`
+   * :doc:`bpm/spring <pair_bpm_spring>`
    * :doc:`brownian (o) <pair_brownian>`
    * :doc:`brownian/poly (o) <pair_brownian>`
    * :doc:`buck (giko) <pair_buck>`
@@ -88,12 +89,12 @@ OPT.
    * :doc:`coul/tt <pair_coul_tt>`
    * :doc:`coul/wolf (ko) <pair_coul>`
    * :doc:`coul/wolf/cs <pair_cs>`
-   * :doc:`dpd (gio) <pair_dpd>`
+   * :doc:`dpd (giko) <pair_dpd>`
    * :doc:`dpd/fdt <pair_dpd_fdt>`
-   * :doc:`dpd/ext <pair_dpd_ext>`
+   * :doc:`dpd/ext (k) <pair_dpd_ext>`
-   * :doc:`dpd/ext/tstat <pair_dpd_ext>`
+   * :doc:`dpd/ext/tstat (k) <pair_dpd_ext>`
    * :doc:`dpd/fdt/energy (k) <pair_dpd_fdt>`
-   * :doc:`dpd/tstat (go) <pair_dpd>`
+   * :doc:`dpd/tstat (gko) <pair_dpd>`
    * :doc:`dsmc <pair_dsmc>`
    * :doc:`e3b <pair_e3b>`
    * :doc:`drip <pair_drip>`
@@ -119,10 +120,12 @@ OPT.
    * :doc:`granular <pair_granular>`
    * :doc:`gw <pair_gw>`
    * :doc:`gw/zbl <pair_gw>`
+   * :doc:`harmonic/cut (o) <pair_harmonic_cut>`
    * :doc:`hbond/dreiding/lj (o) <pair_hbond_dreiding>`
    * :doc:`hbond/dreiding/morse (o) <pair_hbond_dreiding>`
    * :doc:`hdnnp <pair_hdnnp>`
-   * :doc:`ilp/graphene/hbn <pair_ilp_graphene_hbn>`
+   * :doc:`ilp/graphene/hbn (t) <pair_ilp_graphene_hbn>`
+   * :doc:`ilp/tmd <pair_ilp_tmd>`
    * :doc:`kolmogorov/crespi/full <pair_kolmogorov_crespi_full>`
    * :doc:`kolmogorov/crespi/z <pair_kolmogorov_crespi_z>`
    * :doc:`lcbop <pair_lcbop>`
@@ -149,7 +152,7 @@ OPT.
    * :doc:`lj/cut/coul/cut/dielectric (o) <pair_dielectric>`
    * :doc:`lj/cut/coul/cut/soft (o) <pair_fep_soft>`
    * :doc:`lj/cut/coul/debye (gko) <pair_lj_cut_coul>`
-   * :doc:`lj/cut/coul/debye/dielectric <pair_dielectric>`
+   * :doc:`lj/cut/coul/debye/dielectric (o) <pair_dielectric>`
    * :doc:`lj/cut/coul/dsf (gko) <pair_lj_cut_coul>`
    * :doc:`lj/cut/coul/long (gikot) <pair_lj_cut_coul>`
    * :doc:`lj/cut/coul/long/cs <pair_cs>`
@@ -210,6 +213,7 @@ OPT.
    * :doc:`nm/cut (o) <pair_nm>`
    * :doc:`nm/cut/coul/cut (o) <pair_nm>`
    * :doc:`nm/cut/coul/long (o) <pair_nm>`
+   * :doc:`nm/cut/split <pair_nm>`
    * :doc:`oxdna/coaxstk <pair_oxdna>`
    * :doc:`oxdna/excv <pair_oxdna>`
    * :doc:`oxdna/hbond <pair_oxdna>`
@@ -239,6 +243,7 @@ OPT.
    * :doc:`reaxff (ko) <pair_reaxff>`
    * :doc:`rebo (io) <pair_airebo>`
    * :doc:`resquared (go) <pair_resquared>`
+   * :doc:`saip/metal <pair_saip_metal>`
    * :doc:`sdpd/taitwater/isothermal <pair_sdpd_taitwater_isothermal>`
    * :doc:`smatb <pair_smatb>`
    * :doc:`smatb/single <pair_smatb>`
@@ -264,6 +269,7 @@ OPT.
    * :doc:`spin/neel <pair_spin_neel>`
    * :doc:`srp <pair_srp>`
    * :doc:`sw (giko) <pair_sw>`
+   * :doc:`sw/mod (o) <pair_sw>`
    * :doc:`table (gko) <pair_table>`
    * :doc:`table/rx (k) <pair_table_rx>`
    * :doc:`tdpd <pair_mesodpd>`

doc/src/Developer.rst

@@ -11,7 +11,9 @@ of time and requests from the LAMMPS user community.
    :maxdepth: 1
 
    Developer_org
+   Developer_code_design
    Developer_parallel
+   Developer_comm_ops
    Developer_flow
    Developer_write
    Developer_notes

doc/src/Developer_code_design.rst

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

doc/src/Developer_comm_ops.rst

@@ -0,0 +1,235 @@
+Communication patterns
+----------------------
+
+This page describes various inter-processor communication operations
+provided by LAMMPS, mostly in the core *Comm* class.  These are operations
+for common tasks implemented using MPI library calls.  They are used by
+other classes to perform communication of different kinds.  These
+operations are useful to know about when writing new code for LAMMPS
+that needs to communicate data between processors.
+
+Owned and ghost atoms
+^^^^^^^^^^^^^^^^^^^^^
+
+As described on the :doc:`parallel partitioning algorithms
+<Developer_par_part>` page, LAMMPS spatially decomposes the simulation
+domain, either in a *brick* or *tiled* manner.  Each processor (MPI
+task) owns atoms within its sub-domain and additionally stores ghost
+atoms within a cutoff distance of its sub-domain.
+
+Forward and reverse communication
+=================================
+
+As described on the :doc:`parallel communication algorithms
+<Developer_par_comm>` page, the most common communication operations are
+first, *forward communication* which sends owned atom information from
+each processor to nearby processors to store with their ghost atoms.
+The need to do this communication arises when data from the owned atoms
+is updated (e.g. their positions) and this updated information needs to
+be **copied** to the corresponding ghost atoms.
+
+And second, *reverse communication* which sends ghost atom information
+from each processor to the owning processor to **accumulate** (sum)
+the values with the corresponding owned atoms.  The need for this
+arises when data is computed and also stored with ghost atoms
+(e.g. forces when using a "half" neighbor list) and thus those terms
+need to be added to their corresponding atoms on the process where
+they are "owned" atoms.  Please note, that with the :doc:`newton off
+<newton>` setting this does not happen and the neighbor lists are
+constructed so that these interactions are computed on both MPI
+processes containing one of the atoms and only the data pertaining to
+the local atom is stored.
+
+The time-integration classes in LAMMPS invoke these operations each
+timestep via the *forward_comm()* and *reverse_comm()* methods in the
+*Comm* class.  Which per-atom data is communicated depends on the
+currently used :doc:`atom style <atom_style>` and whether
+:doc:`comm_modify vel <comm_modify>` setting is "no" (default) or
+"yes".
+
+Similarly, *Pair* style classes can invoke the *forward_comm(this)*
+and *reverse_comm(this)* methods in the *Comm* class to perform the
+same operations on per-atom data that is generated and stored within
+the pair style class. Note that this function requires passing the
+``this`` pointer as the first argument to enable the *Comm* class to
+call the "pack" and "unpack" functions discussed below.  An example of
+the use of these functions are many-body pair styles like the
+embedded-atom method (EAM) which compute intermediate values in the
+first part of the compute() function that need to be stored by both
+owned and ghost atoms for the second part of the force computation.
+The *Comm* class methods perform the MPI communication for buffers of
+per-atom data.  They "call back" to the *Pair* class so it can *pack*
+or *unpack* the buffer with data the *Pair* class owns.  There are 4
+such methods that the *Pair* class must define, assuming it uses both
+forward and reverse communication:
+
+* pack_forward_comm()
+* unpack_forward_comm()
+* pack_reverse_comm()
+* unpack_reverse_comm()
+
+The arguments to these methods include the buffer and a list of atoms
+to pack or unpack.  The *Pair* class also must set the *comm_forward*
+and *comm_reverse* variables which store the number of values stored
+in the communication buffers for each operation.  This means, if
+desired, it can choose to store multiple per-atom values in the
+buffer, and they will be communicated together to minimize
+communication overhead.  The communication buffers are defined vectors
+containing ``double`` values.  To correctly store integers that may be
+64-bit (bigint, tagint, imageint) in the buffer, you need to use the
+`ubuf union <Communication buffer coding with ubuf>`_ construct.
+
+The *Fix*, *Compute*, and *Dump* classes can also invoke the same kind
+of forward and reverse communication operations using the same *Comm*
+class methods.  Likewise the same pack/unpack methods and
+comm_forward/comm_reverse variables must be defined by the calling
+*Fix*, *Compute*, or *Dump* class.
+
+For *Fix* classes there is an optional second argument to the
+*forward_comm()* and *reverse_comm()* call which can be used when the
+fix performs multiple modes of communication, with different numbers
+of values per atom.  The fix should set the *comm_forward* and
+*comm_reverse* variables to the maximum value, but can invoke the
+communication for a particular mode with a smaller value.  For this
+to work, the *pack_forward_comm()*, etc methods typically use a class
+member variable to choose which values to pack/unpack into/from the
+buffer.
+
+Finally, for reverse communications in *Fix* classes there is also the
+*reverse_comm_variable()* method that allows the communication to have
+a different amount of data per-atom.  It invokes these corresponding
+callback methods:
+
+* pack_reverse_comm_size()
+* unpack_reverse_comm_size()
+
+which have extra arguments to specify the amount of data stored
+in the buffer for each atom.
+
+Higher level communication
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are also several higher-level communication operations provided
+in LAMMPS which work for either *brick* or *tiled* decompositions.
+They may be useful for a new class to invoke if it requires more
+sophisticated communication than the *forward* and *reverse* methods
+provide.  The 3 communication operations described here are
+
+* ring
+* irregular
+* rendezvous
+
+You can invoke these *grep* command in the LAMMPS src directory, to
+see a list of classes that invoke the 3 operations.
+
+* ``grep "\->ring" *.cpp */*.cpp``
+* ``grep "irregular\->" *.cpp``
+* ``grep "\->rendezvous" *.cpp */*.cpp``
+
+Ring operation
+==============
+
+The *ring* operation is invoked via the *ring()* method in the *Comm*
+class.
+
+Each processor first creates a buffer with a list of values, typically
+associated with a subset of the atoms it owns.  Now think of the *P*
+processors as connected to each other in a *ring*.  Each processor *M*
+sends data to the next *M+1* processor.  It receives data from the
+preceding *M-1* processor.  The ring is periodic so that the last
+processor sends to the first processor, and the first processor
+receives from the last processor.
+
+Invoking the *ring()* method passes each processor's buffer in *P*
+steps around the ring.  At each step a *callback* method, provided as
+an argument to ring(), in the caller is invoked.  This allows each
+processor to examine the data buffer provided by every other
+processor.  It may extract values needed by its atoms from the
+buffers, or it may alter placeholder values in the buffer.  In the
+latter case, when the *ring* operation is complete, each processor can
+examine its original buffer to extract modified values.
+
+Note that the *ring* operation is similar to an MPI_Alltoall()
+operation where every processor effectively sends and receives data to
+every other processor.  The difference is that the *ring* operation
+does it one step at a time, so the total volume of data does not need
+to be stored by every processor.  However, the *ring* operation is
+also less efficient than MPI_Alltoall() because of the *P* stages
+required.  So it is typically only suitable for small data buffers and
+occasional operations that are not time-critical.
+
+Irregular operation
+===================
+
+The *irregular* operation is provided by the *Irregular* class.  What
+LAMMPS terms irregular communication is when each processor knows what
+data it needs to send to what processor, but does not know what
+processors are sending it data.  An example is when load-balancing is
+performed and each processor needs to send some of its atoms to new
+processors.
+
+The *Irregular* class provides 5 high-level methods useful in this
+context:
+
+* create_data()
+* exchange_data()
+* create_atom()
+* exchange_atom()
+* migrate_atoms()
+
+For the *create_data()* method, each processor specifies a list of *N*
+datums to send, each to a specified processor.  Internally, the method
+creates efficient data structures for performing the communication.
+The *exchange_data()* method triggers the communication to be
+performed.  Each processor provides the vector of *N* datums to send,
+and the size of each datum.  All datums must be the same size.
+
+The *create_atom()* and *exchange_atom()* methods are similar except
+that the size of each datum can be different.  Typically this is used
+to communicate atoms, each with a variable amount of per-atom data, to
+other processors.
+
+The *migrate_atoms()* method is a convenience wrapper on the
+*create_atom()* and *exchange_atom()* methods to simplify
+communication of all the per-atom data associated with an atom so that
+the atom can effectively migrate to a new owning processor.  It is
+similar to the *exchange()* method in the *Comm* class invoked when
+atoms move to neighboring processors (in the regular or tiled
+decomposition) during timestepping, except that it allows atoms to
+have moved arbitrarily long distances and still be properly
+communicated to a new owning processor.
+
+Rendezvous operation
+====================
+
+Finally, the *rendezvous* operation is invoked via the *rendezvous()*
+method in the *Comm* class.  Depending on how much communication is
+needed and how many processors a LAMMPS simulation is running on, it
+can be a much more efficient choice than the *ring()* method.  It uses
+the *irregular* operation internally once or twice to do its
+communication.  The rendezvous algorithm is described in detail in
+:ref:`(Plimpton) <Plimpton>`, including some LAMMPS use cases.
+
+For the *rendezvous()* method, each processor specifies a list of *N*
+datums to send and which processor to send each of them to.
+Internally, this communication is performed as an irregular operation.
+The received datums are returned to the caller via invocation of
+*callback* function, provided as an argument to *rendezvous()*.  The
+caller can then process the received datums and (optionally) assemble
+a new list of datums to communicate to a new list of specific
+processors.  When the callback function exits, the *rendezvous()*
+method performs a second irregular communication on the new list of
+datums.
+
+Examples in LAMMPS of use of the *rendezvous* operation are the
+:doc:`fix rigid/small <fix_rigid>` and :doc:`fix shake
+<fix_shake>` commands (for one-time identification of the rigid body
+atom clusters) and the identification of special_bond 1-2, 1-3 and 1-4
+neighbors within molecules.  See the :doc:`special_bonds <special_bonds>`
+command for context.
+
+----------
+
+.. _Plimpton:
+
+**(Plimpton)** Plimpton and Knight, JPDC, 147, 184-195 (2021).

doc/src/Developer_notes.rst

@@ -7,6 +7,215 @@ typically document what a variable stores, what a small section of
 code does, or what a function does and its input/outputs.  The topics
 on this page are intended to document code functionality at a higher level.
 
+Available topics are:
+
+- `Reading and parsing of text and text files`_
+- `Requesting and accessing neighbor lists`_
+- `Fix contributions to instantaneous energy, virial, and cumulative energy`_
+- `KSpace PPPM FFT grids`_
+
+----
+
+Reading and parsing of text and text files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is frequently required for a class in LAMMPS to read in additional
+data from a file, e.g. potential parameters from a potential file for
+manybody potentials.  LAMMPS provides several custom classes and
+convenience functions to simplify the process.  They offer the
+following benefits:
+
+- better code reuse and fewer lines of code needed to implement reading
+  and parsing data from a file
+- better detection of format errors, incompatible data, and better error messages
+- exit with an error message instead of silently converting only part of the
+  text to a number or returning a 0 on unrecognized text and thus reading incorrect values
+- re-entrant code through avoiding global static variables (as used by ``strtok()``)
+- transparent support for translating unsupported UTF-8 characters to their ASCII equivalents
+  (the text-to-value conversion functions **only** accept ASCII characters)
+
+In most cases (e.g. potential files) the same data is needed on all MPI
+ranks.  Then it is best to do the reading and parsing only on MPI rank
+0, and communicate the data later with one or more ``MPI_Bcast()``
+calls.  For reading generic text and potential parameter files the
+custom classes :cpp:class:`TextFileReader <LAMMPS_NS::TextFileReader>`
+and :cpp:class:`PotentialFileReader <LAMMPS_NS::PotentialFileReader>`
+are available. They allow reading the file as individual lines for which
+they can return a tokenizer class (see below) for parsing the line.  Or
+they can return blocks of numbers as a vector directly.  The
+documentation on :ref:`File reader classes <file-reader-classes>`
+contains an example for a typical case.
+
+When reading per-atom data, the data on each line of the file usually
+needs to include an atom ID so it can be associated with a particular
+atom.  In that case the data can be read in multi-line chunks and
+broadcast to all MPI ranks with
+:cpp:func:`utils::read_lines_from_file()
+<LAMMPS_NS::utils::read_lines_from_file>`.  Those chunks are then
+split into lines, parsed, and applied only to atoms the MPI rank
+"owns".
+
+For splitting a string (incrementally) into words and optionally
+converting those to numbers, the :cpp:class:`Tokenizer
+<LAMMPS_NS::Tokenizer>` and :cpp:class:`ValueTokenizer
+<LAMMPS_NS::ValueTokenizer>` can be used.  Those provide a superset of
+the functionality of ``strtok()`` from the C-library and the latter
+also includes conversion to different types.  Any errors while
+processing the string in those classes will result in an exception,
+which can be caught and the error processed as needed.  Unlike the
+C-library functions ``atoi()``, ``atof()``, ``strtol()``, or
+``strtod()`` the conversion will check if the converted text is a
+valid integer or floating point number and will not silently return an
+unexpected or incorrect value.  For example, ``atoi()`` will return 12
+when converting "12.5", while the ValueTokenizer class will throw an
+:cpp:class:`InvalidIntegerException
+<LAMMPS_NS::InvalidIntegerException>` if
+:cpp:func:`ValueTokenizer::next_int()
+<LAMMPS_NS::ValueTokenizer::next_int>` is called on the same string.
+
+Requesting and accessing neighbor lists
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+LAMMPS uses Verlet-style neighbor lists to avoid having to loop over
+*all* pairs of *all* atoms when computing pairwise properties with a
+cutoff (e.g. pairwise forces or radial distribution functions).  There
+are three main algorithms that can be selected by the :doc:`neighbor
+command <neighbor>`: `bin` (the default, uses binning to achieve linear
+scaling with system size), `nsq` (without binning, quadratic scaling),
+`multi` (with binning, optimized for varying cutoffs or polydisperse
+granular particles).  In addition to how the neighbor lists are
+constructed a number of different variants of neighbor lists need to be
+created (e.g. "full" or "half") for different purposes and styles and
+those may be required in every time step ("perpetual") or on some steps
+("occasional").
+
+The neighbor list creation is managed by the ``Neighbor`` class.
+Individual classes can obtain a neighbor list by creating an instance of
+a ``NeighRequest`` class which is stored in a list inside the
+``Neighbor`` class.  The ``Neighbor`` class will then analyze the
+various requests and apply optimizations where neighbor lists that have
+the same settings will be created only once and then copied, or a list
+may be constructed by processing a neighbor list from a different
+request that is a superset of the requested list.  The neighbor list
+build is then :doc:`processed in parallel <Developer_par_neigh>`.
+
+The most commonly required neighbor list is a so-called "half" neighbor
+list, where each pair of atoms is listed only once (except when the
+:doc:`newton command setting <newton>` for pair is off; in that case
+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++
+
+   void Pair::init_style()
+   {
+     neighbor->add_request(this);
+   }
+
+   void Pair::init_list(int /*id*/, NeighList *ptr)
+   {
+     list = ptr;
+   }
+
+The ``this`` pointer argument is required so the neighbor list code can
+access the requesting class instance to store the assembled neighbor
+list with that instance by calling its ``init_list()`` member function.
+The optional second argument (omitted here) contains a bitmask of flags
+that determines the kind of neighbor list requested.  The default value
+used here asks for a perpetual "half" neighbor list.
+
+Non-default values of the second argument need to be used to adjust a
+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++
+
+   void PairTersoff::init_style()
+   {
+     // [...]
+     neighbor->add_request(this, NeighConst::REQ_FULL);
+   }
+
+When a pair style supports r-RESPA time integration with different cutoff regions,
+the request flag may depend on the corresponding r-RESPA settings. Here an example
+from pair style lj/cut:
+
+.. code-block:: C++
+
+   void PairLJCut::init_style()
+   {
+     int list_style = NeighConst::REQ_DEFAULT;
+
+     if (update->whichflag == 1 && utils::strmatch(update->integrate_style, "^respa")) {
+       auto respa = (Respa *) update->integrate;
+       if (respa->level_inner >= 0) list_style = NeighConst::REQ_RESPA_INOUT;
+       if (respa->level_middle >= 0) list_style = NeighConst::REQ_RESPA_ALL;
+     }
+     neighbor->add_request(this, list_style);
+     // [...]
+   }
+
+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++
+
+   if (use_history) neighbor->add_request(this, NeighConst::REQ_SIZE | NeighConst::REQ_HISTORY);
+   else neighbor->add_request(this, NeighConst::REQ_SIZE);
+
+In case a class would need to make multiple neighbor list requests with different
+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++
+
+   void PairMEAM::init_style()
+   {
+   // [...]
+     neighbor->add_request(this, NeighConst::REQ_FULL)->set_id(1);
+     neighbor->add_request(this)->set_id(2);
+   }
+   void PairMEAM::init_list(int id, NeighList *ptr)
+   {
+     if (id == 1) listfull = ptr;
+     else if (id == 2) listhalf = ptr;
+   }
+
+Fixes may require a neighbor list that is only build occasionally (or
+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++
+
+   neighbor->add_request(this, NeighConst::REQ_FULL | NeighConst::REQ_OCCASIONAL);
+
+It is also possible to request a neighbor list that uses a different cutoff
+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++
+
+  if (cutflag)
+    neighbor->add_request(this, NeighConst::REQ_OCCASIONAL)->set_cutoff(mycutneigh);
+  else
+    neighbor->add_request(this, NeighConst::REQ_OCCASIONAL);
+
+The neighbor list request function has a slightly different set of arguments
+when created by a command style.  In this case the neighbor list is
+*always* an occasional neighbor list, so that flag is not needed. However
+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++
+
+   neighbor->add_request(this, "delete_atoms", NeighConst::REQ_FULL);
+
 Fix contributions to instantaneous energy, virial, and cumulative energy
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

doc/src/Developer_org.rst

@@ -225,7 +225,7 @@ follows:
   commands in an input script.
 
 - The Force class computes various forces between atoms.  The Pair
-  parent class is for non-bonded or pair-wise forces, which in LAMMPS
+  parent class is for non-bonded or pairwise forces, which in LAMMPS
   also includes many-body forces such as the Tersoff 3-body potential if
   those are computed by walking pairwise neighbor lists.  The Bond,
   Angle, Dihedral, Improper parent classes are styles for bonded
@@ -252,12 +252,6 @@ follows:
 - The Timer class logs timing information, output at the end
   of a run.
 
-.. TODO section on "Spatial decomposition and parallel operations"
-..       diagram of 3d processor grid, brick vs. tiled. local vs. ghost
-..       atoms, 6-way communication with pack/unpack functions,
-..       PBC as part of the communication, forward and reverse communication
-..       rendezvous communication, ring communication.
-
 .. TODO section on "Fixes, Computes, and Variables"
 ..      how and when data is computed and provided and how it is
 ..      referenced. flags in Fix/Compute/Variable classes tell

doc/src/Developer_plugins.rst

@@ -8,11 +8,20 @@ without recompiling LAMMPS.  The functionality for this and the
 
 Plugins use the operating system's capability to load dynamic shared
 object (DSO) files in a way similar shared libraries and then reference
-specific functions in those DSOs.  Any DSO file with plugins has to include
+specific functions in those DSOs.  Any DSO file with plugins has to
-an initialization function with a specific name, "lammpsplugin_init", that
+include an initialization function with a specific name,
-has to follow specific rules described below.  When loading the DSO with
+"lammpsplugin_init", that has to follow specific rules described below.
-the "plugin" command, this function is looked up and called and will then
+When loading the DSO with the "plugin" command, this function is looked
-register the contained plugin(s) with LAMMPS.
+up and called and will then register the contained plugin(s) with
+LAMMPS.
+
+When the environment variable ``LAMMPS_PLUGIN_PATH`` is set, then LAMMPS
+will search the directory (or directories) listed in this path for files
+with names that end in ``plugin.so`` (e.g. ``helloplugin.so``) and will
+try to load the contained plugins automatically at start-up.  For
+plugins that are loaded this way, the behavior of LAMMPS should be
+identical to a binary where the corresponding code was compiled in
+statically as a package.
 
 From the programmer perspective this can work because of the object
 oriented design of LAMMPS where all pair style commands are derived from
@@ -59,25 +68,24 @@ Members of ``lammpsplugin_t``
    * - author
      - String with the name and email of the author
    * - creator.v1
-     - Pointer to factory function for pair, bond, angle, dihedral, improper or command styles
+     - Pointer to factory function for pair, bond, angle, dihedral, improper, kspace, or command styles
    * - creator.v2
      - Pointer to factory function for compute, fix, or region styles
    * - handle
      - Pointer to the open DSO file handle
 
-Only one of the three alternate creator entries can be used at a time
+Only one of the two alternate creator entries can be used at a time and
-and which of those is determined by the style of plugin. The
+which of those is determined by the style of plugin. The "creator.v1"
-"creator.v1" element is for factory functions of supported styles
+element is for factory functions of supported styles computing forces
-computing forces (i.e.  command, pair, bond, angle, dihedral, or
+(i.e. pair, bond, angle, dihedral, or improper styles) or command styles
-improper styles) and the function takes as single argument the pointer
+and the function takes as single argument the pointer to the LAMMPS
-to the LAMMPS instance. The factory function is cast to the
+instance. The factory function is cast to the ``lammpsplugin_factory1``
-``lammpsplugin_factory1`` type before assignment.  The "creator.v2"
+type before assignment.  The "creator.v2" element is for factory
-element is for factory functions creating an instance of a fix, compute,
+functions creating an instance of a fix, compute, or region style and
-or region style and takes three arguments: a pointer to the LAMMPS
+takes three arguments: a pointer to the LAMMPS instance, an integer with
-instance, an integer with the length of the argument list and a ``char
+the length of the argument list and a ``char **`` pointer to the list of
-**`` pointer to the list of arguments. The factory function pointer
+arguments. The factory function pointer needs to be cast to the
-needs to be cast to the ``lammpsplugin_factory2`` type before
+``lammpsplugin_factory2`` type before assignment.
-assignment.
 
 Pair style example
 ^^^^^^^^^^^^^^^^^^
@@ -249,3 +257,29 @@ by ``#ifdef PAIR_CLASS`` is not needed, since the mapping of the class
 name to the style name is done by the plugin registration function with
 the information from the ``lammpsplugin_t`` struct.  It may be included
 in case the new code is intended to be later included in LAMMPS directly.
+
+A plugin may be registered under an existing style name.  In that case
+the plugin will override the existing code.  This can be used to modify
+the behavior of existing styles or to debug new versions of them without
+having to re-compile or re-install all of LAMMPS.
+
+Compiling plugins
+^^^^^^^^^^^^^^^^^
+
+Plugins need to be compiled with the same compilers and libraries
+(e.g. MPI) and compilation settings (MPI on/off, OpenMP, integer sizes)
+as the LAMMPS executable and library.  Otherwise the plugin will likely
+not load due to mismatches in the function signatures (LAMMPS is C++ so
+scope, type, and number of arguments are encoded into the symbol names
+and thus differences in them will lead to failed plugin load commands.
+Compilation of the plugin can be managed via both, CMake or traditional
+GNU makefiles.  Some examples that can be used as a template are in the
+``examples/plugins`` folder.  The CMake script code has some small
+adjustments to allow building the plugins for running unit tests with
+them. Another example that converts the KIM package into a plugin can be
+found in the ``examples/kim/plugin`` folder.  No changes to the sources
+of the KIM package themselves are needed; only the plugin interface and
+loader code needs to be added.  This example only supports building with
+CMake, but is probably a more typical example. To compile you need to
+run CMake with -DLAMMPS_SOURCE_DIR=<path/to/lammps/src/folder>.  Other
+configuration setting are identical to those for compiling LAMMPS.

doc/src/Developer_utils.rst

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

doc/src/Developer_write.rst

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

doc/src/Errors.rst

@@ -11,6 +11,7 @@ them.
    :maxdepth: 1
 
    Errors_common
+   Errors_details
    Errors_bugs
    Errors_debug
    Errors_messages

doc/src/Errors_bugs.rst

@@ -17,9 +17,8 @@ the steps outlined below:
    if your issue has already been reported and if it is still open.
  * Check the `GitHub Pull Requests page <https://github.com/lammps/lammps/pulls>`_
    to see if there is already a fix for your bug pending.
- * Check the `mailing list archives <https://www.lammps.org/mail.html>`_ or
+ * Check the `LAMMPS forum at MatSci <https://matsci.org/lammps/>`_
-   the `LAMMPS forum <https://www.lammps.org/forum.html>`_ to see if the
+   to see if the issue has been discussed before.
-   issue has been discussed before.
 
 If none of these steps yields any useful information, please file a new
 bug report on the `GitHub Issue page <https://github.com/lammps/lammps/issues>`_.
@@ -38,12 +37,9 @@ generate this restart from a data file or a simple additional input.
 This input deck can be used with tools like a debugger or `valgrind
 <https://valgrind.org>`_ to further :doc:`debug the crash <Errors_debug>`.
 
-You may also send an email to the LAMMPS mailing list at
+You may also post a message in the `development category of the LAMMPS
-"lammps-users at lists.sourceforge.net" describing the problem with the
+forum at MatSci <https://matsci.org/c/lammps/lammps-development/>`_
-same kind of information.  The mailing list can provide a faster response,
+describing the problem with the same kind of information.  The forum can
-especially if the bug reported is actually expected behavior.  But because
+provide a faster response, especially if the bug reported is actually
-of the high volume of the mailing list, it can happen that your e-mail
+expected behavior or other LAMMPS users have come across it before.
-is overlooked and then forgotten.  Issues on GitHub have to be explicitly
-closed, so that will *guarantee* that at least one LAMMPS developer will
-have looked at it.
 

doc/src/Errors_details.rst

@@ -0,0 +1,27 @@
+Error and warning details
+=========================
+
+Many errors or warnings are self-explanatory and thus straightforward to
+resolve.  However, there are also cases, where there is no single cause
+and explanation, where LAMMPS can only detect symptoms of an error but
+not the exact cause, or where the explanation needs to be more detailed than
+what can be fit into a message printed by the program.  The following are
+discussions of such cases.
+
+.. _err0001:
+
+Unknown identifier in data file
+-------------------------------
+
+This error happens when LAMMPS encounters a line of text in an unexpected format
+while reading a data file. This is most commonly cause by inconsistent header and
+section data.  The header section informs LAMMPS how many entries or lines are expected in the
+various sections (like Atoms, Masses, Pair Coeffs, *etc.*\ ) of the data file.
+If there is a mismatch, LAMMPS will either keep reading beyond the end of a section
+or stop reading before the section has ended.
+
+Such a mismatch can happen unexpectedly when the first line of the data
+is *not* a comment as required by the format.  That would result in
+LAMMPS expecting, for instance, 0 atoms because the "atoms" header line
+is treated as a comment.
+

doc/src/Errors_messages.rst

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

doc/src/Errors_warnings.rst

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

doc/src/Examples.rst

@@ -54,6 +54,8 @@ Lowercase directories
 +-------------+------------------------------------------------------------------+
 | body        | body particles, 2d system                                        |
 +-------------+------------------------------------------------------------------+
+| bpm         | BPM simulations of pouring elastic grains and plate impact       |
++-------------+------------------------------------------------------------------+
 | cmap        | CMAP 5-body contributions to CHARMM force field                  |
 +-------------+------------------------------------------------------------------+
 | colloid     | big colloid particles in a small particle solvent, 2d system     |
@@ -94,12 +96,12 @@ Lowercase directories
 +-------------+------------------------------------------------------------------+
 | latte       | examples for using fix latte for DFTB via the LATTE library      |
 +-------------+------------------------------------------------------------------+
+| mdi         | use of the MDI package and MolSSI MDI code coupling library      |
++-------------+------------------------------------------------------------------+
 | meam        | MEAM test for SiC and shear (same as shear examples)             |
 +-------------+------------------------------------------------------------------+
 | melt        | rapid melt of 3d LJ system                                       |
 +-------------+------------------------------------------------------------------+
-| message     | demos for LAMMPS client/server coupling with the MESSAGE package |
-+-------------+------------------------------------------------------------------+
 | micelle     | self-assembly of small lipid-like molecules into 2d bilayers     |
 +-------------+------------------------------------------------------------------+
 | min         | energy minimization of 2d LJ melt                                |

doc/src/Howto.rst

@@ -22,8 +22,9 @@ General howto
    Howto_replica
    Howto_library
    Howto_couple
-   Howto_client_server
    Howto_mdi
+   Howto_bpm
+   Howto_broken_bonds
 
 Settings howto
 ==============

doc/src/Howto_bpm.rst

@@ -0,0 +1,119 @@
+Bonded particle models
+======================
+
+The BPM package implements bonded particle models which can be used to
+simulate mesoscale solids.  Solids are constructed as a collection of
+particles which each represent a coarse-grained region of space much
+larger than the atomistic scale. Particles within a solid region are
+then connected by a network of bonds to provide solid elasticity.
+
+Unlike traditional bonds in molecular dynamics, the equilibrium bond
+length can vary between bonds. Bonds store the reference state.  This
+includes setting the equilibrium length equal to the initial distance
+between the two particles but can also include data on the bond
+orientation for rotational models. This produces a stress free initial
+state. Furthermore, bonds are allowed to break under large strains
+producing fracture. The examples/bpm directory has sample input scripts
+for simulations of the fragmentation of an impacted plate and the
+pouring of extended, elastic bodies.
+
+----------
+
+Bonds can be created using a :doc:`read data <read_data>` or
+:doc:`create bonds <create_bonds>` command. Alternatively, a
+:doc:`molecule <molecule>` template with bonds can be used with
+:doc:`fix deposit <fix_deposit>` or :doc:`fix pour <fix_pour>` to
+create solid grains.
+
+In this implementation, bonds store their reference state when they are
+first computed in the setup of the first simulation run. Data is then
+preserved across run commands and is written to :doc:`binary restart
+files <restart>` such that restarting the system will not reset the
+reference state of a bond. Bonds that are created midway into a run,
+such as those created by pouring grains using :doc:`fix pour
+<fix_pour>`, are initialized on that timestep.
+
+As bonds can be broken between neighbor list builds, the
+:doc:`special_bonds <special_bonds>` command works differently for BPM
+bond styles. There are two possible settings which determine how pair
+interactions work between bonded particles.  First, one can turn off
+all pair interactions between bonded particles.  Unlike :doc:`bond
+quartic <bond_quartic>`, this is not done by subtracting pair forces
+during the bond computation but rather by dynamically updating the
+special bond list. This is the default behavior of BPM bond styles and
+is done by updating the 1-2 special bond list as bonds break.  To do
+this, LAMMPS requires :doc:`newton <newton>` bond off such that all
+processors containing an atom know when a bond breaks. Additionally,
+one must do either (A) or (B).
+
+A) Use the following special bond settings
+
+   .. code-block:: LAMMPS
+
+      special_bonds lj 0 1 1 coul 1 1 1
+
+   These settings accomplish two goals. First, they turn off 1-3 and 1-4
+   special bond lists, which are not currently supported for BPMs. As
+   BPMs often have dense bond networks, generating 1-3 and 1-4 special
+   bond lists is expensive.  By setting the lj weight for 1-2 bonds to
+   zero, this turns off pairwise interactions.  Even though there are no
+   charges in BPM models, setting a nonzero coul weight for 1-2 bonds
+   ensures all bonded neighbors are still included in the neighbor list
+   in case bonds break between neighbor list builds.
+
+B) Alternatively, one can simply overlay pair interactions such that all
+   bonded particles also feel pair interactions. This can be
+   accomplished by using the *overlay/pair* keyword present in all bpm
+   bond styles and by using the following special bond settings
+
+   .. code-block:: LAMMPS
+
+      special_bonds lj/coul 1 1 1
+
+See the :doc:`Howto <Howto_broken_bonds>` page on broken bonds for
+more information.
+
+----------
+
+Currently there are two types of bonds included in the BPM
+package. The first bond style, :doc:`bond bpm/spring
+<bond_bpm_spring>`, only applies pairwise, central body forces. Point
+particles must have :doc:`bond atom style <atom_style>` and may be
+thought of as nodes in a spring network. Alternatively, the second
+bond style, :doc:`bond bpm/rotational <bond_bpm_rotational>`, resolves
+tangential forces and torques arising with the shearing, bending, and
+twisting of the bond due to rotation or displacement of particles.
+Particles are similar to those used in the :doc:`granular package
+<Howto_granular>`, :doc:`atom style sphere <atom_style>`. However,
+they must also track the current orientation of particles and store bonds
+and therefore use a :doc:`bpm/sphere atom style <atom_style>`.
+This also requires a unique integrator :doc:`fix nve/bpm/sphere
+<fix_nve_bpm_sphere>` which numerically integrates orientation similar
+to :doc:`fix nve/asphere <fix_nve_asphere>`.
+
+To monitor the fracture of bonds in the system, all BPM bond styles
+have the ability to record instances of bond breakage to output using
+the :doc:`dump local <dump>` command. Additionally, one can use
+:doc:`compute nbond/atom <compute_nbond_atom>` to tally the current
+number of bonds per atom.
+
+In addition to bond styles, a new pair style :doc:`pair bpm/spring
+<pair_bpm_spring>` was added to accompany the bpm/spring bond
+style. This pair style is simply a hookean repulsion with similar
+velocity damping as its sister bond style.
+
+----------
+
+While LAMMPS has many utilities to create and delete bonds, *only*
+the following are currently compatible with BPM bond styles:
+
+* :doc:`create_bonds <create_bonds>`
+* :doc:`delete_bonds <delete_bonds>`
+* :doc:`fix bond/create <fix_bond_create>`
+* :doc:`fix bond/break <fix_bond_break>`
+* :doc:`fix bond/swap <fix_bond_swap>`
+
+Note :doc:`create_bonds <create_bonds>` requires certain special_bonds settings.
+To subtract pair interactions, one will need to switch between different
+special_bonds settings in the input script. An example is found in
+examples/bpm/impact.

doc/src/Howto_broken_bonds.rst

@@ -0,0 +1,48 @@
+Broken Bonds
+============
+
+Typically, bond interactions persist for the duration of a simulation
+in LAMMPS. However, there are some exceptions that allow for bonds to
+break including the :doc:`quartic bond style <bond_quartic>` and the
+bond styles in the :doc:`BPM package <Howto_bpm>` which contains the
+:doc:`bpm/spring <bond_bpm_spring>` and
+:doc:`bpm/rotational <bond_bpm_rotational>` bond styles. In these cases,
+a bond can be broken if it is stretched beyond a user-defined threshold.
+LAMMPS accomplishes this by setting the bond type to zero such that the
+bond force is no longer computed.
+
+Users are normally able to weight the contribution of pair forces to atoms
+that are bonded using the :doc:`special_bonds command <special_bonds>`.
+When bonds break, this is not always the case. For the quartic bond style,
+pair forces are always turned off between bonded particles. LAMMPS does
+this via a computational sleight-of-hand. It subtracts the pairwise
+interaction as part of the bond computation. When the bond breaks, the
+subtraction stops.  For this to work, the pairwise interaction must always
+be computed by the :doc:`pair_style <pair_style>` command, whether the bond
+is broken or not.  This means that :doc:`special_bonds <special_bonds>` must
+be set to 1,1,1. After the bond breaks, the pairwise interaction between the
+two atoms is turned on, since they are no longer bonded.
+
+In the BPM package, one can either turn off all pair interactions between
+bonded particles or leave them on, overlaying pair forces on top of bond
+forces. To remove pair forces, the special bond list is dynamically
+updated. More details can be found on the :doc:`Howto BPM <Howto_bpm>`
+page.
+
+Bonds can also be broken by fixes which change bond topology, including
+:doc:`fix bond/break <fix_bond_break>` and
+:doc:`fix bond/react <fix_bond_react>`. These fixes will automatically
+trigger a rebuild of the neighbor list and update special bond data structures
+when bonds are broken.
+
+Note that when bonds are dumped to a file via the :doc:`dump local <dump>` command, bonds with type 0 are not included.  The
+:doc:`delete_bonds <delete_bonds>` command can also be used to query the
+status of broken bonds or permanently delete them, e.g.:
+
+.. code-block:: LAMMPS
+
+   delete_bonds all stats
+   delete_bonds all bond 0 remove
+
+The compute :doc:`nbond/atom <compute_nbond_atom>` can also be used
+to tally the current number of bonds per atom, excluding broken bonds.

doc/src/Howto_client_server.rst

@@ -1,163 +0,0 @@
-Using LAMMPS in client/server mode
-==================================
-
-Client/server coupling of two codes is where one code is the "client"
-and sends request messages to a "server" code.  The server responds to
-each request with a reply message.  This enables the two codes to work
-in tandem to perform a simulation.  LAMMPS can act as either a client
-or server code.
-
-Some advantages of client/server coupling are that the two codes run
-as stand-alone executables; they are not linked together.  Thus
-neither code needs to have a library interface.  This often makes it
-easier to run the two codes on different numbers of processors.  If a
-message protocol (format and content) is defined for a particular kind
-of simulation, then in principle any code that implements the
-client-side protocol can be used in tandem with any code that
-implements the server-side protocol, without the two codes needing to
-know anything more specific about each other.
-
-A simple example of client/server coupling is where LAMMPS is the
-client code performing MD timestepping.  Each timestep it sends a
-message to a server quantum code containing current coords of all the
-atoms.  The quantum code computes energy and forces based on the
-coords.  It returns them as a message to LAMMPS, which completes the
-timestep.
-
-A more complex example is where LAMMPS is the client code and
-processes a series of data files, sending each configuration to a
-quantum code to compute energy and forces.  Or LAMMPS runs dynamics
-with an atomistic force field, but pauses every N steps to ask the
-quantum code to compute energy and forces.
-
-Alternate methods for code coupling with LAMMPS are described on
-the :doc:`Howto couple <Howto_couple>` doc page.
-
-The protocol for using LAMMPS as a client is to use these 3 commands
-in this order (other commands may come in between):
-
-* :doc:`message client <message>`  # initiate client/server interaction
-* :doc:`fix client/md <fix_client_md>`   # any client fix which makes specific requests to the server
-* :doc:`message quit <message>`    # terminate client/server interaction
-
-In between the two message commands, a client fix command and
-:doc:`unfix <unfix>` command can be used multiple times.  Similarly,
-this sequence of 3 commands can be repeated multiple times, assuming
-the server program operates in a similar fashion, to initiate and
-terminate client/server communication.
-
-The protocol for using LAMMPS as a server is to use these 2 commands
-in this order (other commands may come in between):
-
-* :doc:`message server <message>`  # initiate client/server interaction
-* :doc:`server md <server_md>`    # any server command which responds to specific requests from the client
-
-This sequence of 2 commands can be repeated multiple times, assuming
-the client program operates in a similar fashion, to initiate and
-terminate client/server communication.
-
-LAMMPS support for client/server coupling is in its :ref:`MESSAGE package <PKG-MESSAGE>` which implements several
-commands that enable LAMMPS to act as a client or server, as discussed
-below.  The MESSAGE package also wraps a client/server library called
-CSlib which enables two codes to exchange messages in different ways,
-either via files, sockets, or MPI.  The CSlib is provided with LAMMPS
-in the lib/message dir.  The CSlib has its own
-`website <https://cslib.sandia.gov>`_ with documentation and test
-programs.
-
-.. note::
-
-   For client/server coupling to work between LAMMPS and another
-   code, the other code also has to use the CSlib.  This can sometimes be
-   done without any modifications to the other code by simply wrapping it
-   with a Python script that exchanges CSlib messages with LAMMPS and
-   prepares input for or processes output from the other code.  The other
-   code also has to implement a matching protocol for the format and
-   content of messages that LAMMPS exchanges with it.
-
-These are the commands currently in the MESSAGE package for two
-protocols, MD and MC (Monte Carlo).  New protocols can easily be
-defined and added to this directory, where LAMMPS acts as either the
-client or server.
-
-* :doc:`message <message>`
-* :doc:`fix client md <fix_client_md>` = LAMMPS is a client for running MD
-* :doc:`server md <server_md>` = LAMMPS is a server for computing MD forces
-* :doc:`server mc <server_mc>` = LAMMPS is a server for computing a Monte Carlo energy
-
-The server doc files give details of the message protocols
-for data that is exchanged between the client and server.
-
-These example directories illustrate how to use LAMMPS as either a
-client or server code:
-
-* examples/message
-* examples/COUPLE/README
-* examples/COUPLE/lammps_mc
-* examples/COUPLE/lammps_nwchem
-* examples/COUPLE/lammps_vasp
-
-The examples/message directory couples a client instance of LAMMPS to a
-server instance of LAMMPS.
-
-The files in the *lammps_mc* folder show how to couple LAMMPS as
-a server to a simple Monte Carlo client code as the driver.
-
-The files in the *lammps_nwchem* folder show how to couple LAMMPS
-as a client code running MD timestepping to NWChem acting as a
-server providing quantum DFT forces, through a Python wrapper script
-on NWChem.
-
-The files in the *lammps_vasp* folder show how to couple LAMMPS as
-a client code running MD timestepping to VASP acting as a server
-providing quantum DFT forces, through a Python wrapper script on VASP.
-
-Here is how to launch a client and server code together for any of the
-4 modes of message exchange that the :doc:`message <message>` command
-and the CSlib support.  Here LAMMPS is used as both the client and
-server code.  Another code could be substituted for either.
-
-The examples below show launching both codes from the same window (or
-batch script), using the "&" character to launch the first code in the
-background.  For all modes except *mpi/one*, you could also launch the
-codes in separate windows on your desktop machine.  It does not
-matter whether you launch the client or server first.
-
-In these examples either code can be run on one or more processors.
-If running in a non-MPI mode (file or zmq) you can launch a code on a
-single processor without using mpirun.
-
-IMPORTANT: If you run in mpi/two mode, you must launch both codes via
-mpirun, even if one or both of them runs on a single processor.  This
-is so that MPI can figure out how to connect both MPI processes
-together to exchange MPI messages between them.
-
-For message exchange in *file*, *zmq*, or *mpi/two* modes:
-
-.. code-block:: bash
-
-   % mpirun -np 1 lmp_mpi -log log.client < in.client &
-   % mpirun -np 2 lmp_mpi -log log.server < in.server
-
-   % mpirun -np 4 lmp_mpi -log log.client < in.client &
-   % mpirun -np 1 lmp_mpi -log log.server < in.server
-
-   % mpirun -np 2 lmp_mpi -log log.client < in.client &
-   % mpirun -np 4 lmp_mpi -log log.server < in.server
-
-For message exchange in *mpi/one* mode:
-
-Launch both codes in a single mpirun command:
-
-.. code-block:: bash
-
-   mpirun -np 2 lmp_mpi -mpicolor 0 -in in.message.client -log log.client : -np 4 lmp_mpi -mpicolor 1 -in in.message.server -log log.server
-
-The two -np values determine how many procs the client and the server
-run on.
-
-A LAMMPS executable run in this manner must use the -mpicolor color
-command-line option as their its option, where color is an integer
-label that will be used to distinguish one executable from another in
-the multiple executables that the mpirun command launches.  In this
-example the client was colored with a 0, and the server with a 1.

doc/src/Howto_couple.rst

@@ -12,16 +12,16 @@ LAMMPS can be coupled to other codes in at least 4 ways.  Each has
 advantages and disadvantages, which you will have to think about in the
 context of your application.
 
-1. Define a new :doc:`fix <fix>` command that calls the other code.  In
+1. Define a new :doc:`fix <fix>` command that calls the other code.
-   this scenario, LAMMPS is the driver code.  During timestepping,
+   In this scenario, LAMMPS is the driver code.  During timestepping,
    the fix is invoked, and can make library calls to the other code,
-   which has been linked to LAMMPS as a library.  This is the way how the
+   which has been linked to LAMMPS as a library.  This is the way the
    :ref:`LATTE <PKG-LATTE>` package, which performs density-functional
-   tight-binding calculations using the `LATTE software <https://github.com/lanl/LATTE>`_
+   tight-binding calculations using the `LATTE software
-   to compute forces, is hooked to LAMMPS.
+   <https://github.com/lanl/LATTE>`_ to compute forces, is hooked to
-   See the :doc:`fix latte <fix_latte>` command for more details.
+   LAMMPS.  See the :doc:`fix latte <fix_latte>` command for more
-   Also see the :doc:`Modify <Modify>` doc pages for info on how to
+   details.  Also see the :doc:`Modify <Modify>` doc pages for info on
-   add a new fix to LAMMPS.
+   how to add a new fix to LAMMPS.
 
 .. spacer
 
@@ -58,6 +58,12 @@ context of your application.
 
 .. spacer
 
-4. Couple LAMMPS with another code in a client/server mode.  This is
+4. Couple LAMMPS with another code in a client/server fashion, using
-   described on the :doc:`Howto client/server <Howto_client_server>` doc
+   using the `MDI Library
-   page.
+   <https://molssi-mdi.github.io/MDI_Library/html/index.html>`_
+   developed by the `Molecular Sciences Software Institute (MolSSI)
+   <https://molssi.org>`_ to run LAMMPS as either an MDI driver
+   (client) or an MDI engine (server).  The MDI driver issues commands
+   to the MDI server to exchange data between them.  See the
+   :doc:`Howto mdi <Howto_mdi>` page for more information about how
+   LAMMPS can operate in either of these modes.

doc/src/Howto_drude2.rst

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

doc/src/Howto_elastic.rst

@@ -18,23 +18,52 @@ At zero temperature, it is easy to estimate these derivatives by
 deforming the simulation box in one of the six directions using the
 :doc:`change_box <change_box>` command and measuring the change in the
 stress tensor. A general-purpose script that does this is given in the
-examples/elastic directory described on the :doc:`Examples <Examples>`
+examples/ELASTIC directory described on the :doc:`Examples <Examples>`
 doc page.
 
 Calculating elastic constants at finite temperature is more
 challenging, because it is necessary to run a simulation that performs
-time averages of differential properties. One way to do this is to
+time averages of differential properties. There are at least
-measure the change in average stress tensor in an NVT simulations when
+3 ways to do this in LAMMPS. The most reliable way to do this is
+by exploiting the relationship between elastic constants, stress
+fluctuations, and the Born matrix, the second derivatives of energy
+w.r.t. strain :ref:`(Ray) <Ray>`.
+The Born matrix calculation has been enabled by
+the :doc:`compute born/matrix <compute_born_matrix>` command,
+which works for any bonded or non-bonded potential in LAMMPS.
+The most expensive part of the calculation is the sampling of
+the stress fluctuations. Several examples of this method are
+provided in the examples/ELASTIC_T/BORN_MATRIX directory
+described on the :doc:`Examples <Examples>` doc page.
+
+A second way is to measure
+the change in average stress tensor in an NVT simulations when
 the cell volume undergoes a finite deformation. In order to balance
 the systematic and statistical errors in this method, the magnitude of
 the deformation must be chosen judiciously, and care must be taken to
 fully equilibrate the deformed cell before sampling the stress
-tensor. Another approach is to sample the triclinic cell fluctuations
+tensor. An example of this method is provided in the
+examples/ELASTIC_T/DEFORMATION directory
+described on the :doc:`Examples <Examples>` doc page.
+
+Another approach is to sample the triclinic cell fluctuations
 that occur in an NPT simulation. This method can also be slow to
-converge and requires careful post-processing :ref:`(Shinoda) <Shinoda1>`
+converge and requires careful post-processing :ref:`(Shinoda) <Shinoda1>`.
+We do not provide an example of this method.
+
+A nice review of the advantages and disadvantages of all of these methods
+is provided in the paper by Clavier et al. :ref:`(Clavier) <Clavier>`.
 
 ----------
 
+.. _Ray:
+
+**(Ray)** J. R. Ray and A. Rahman, J Chem Phys, 80, 4423 (1984).
+
 .. _Shinoda1:
 
 **(Shinoda)** Shinoda, Shiga, and Mikami, Phys Rev B, 69, 134103 (2004).
+
+.. _Clavier:
+
+**(Clavier)** G. Clavier, N. Desbiens, E. Bourasseau, V. Lachet, N. Brusselle-Dupend and B. Rousseau, Mol Sim, 43, 1413 (2017).

doc/src/Howto_mdi.rst

@@ -1,132 +1,144 @@
 Using LAMMPS with the MDI library for code coupling
 ===================================================
 
-.. note::
+Client/server coupling of two (or more) codes is where one code is the
-
+"client" and sends request messages (data) to one (or more) "server"
-  This Howto page will eventually replace the
+code(s).  A server responds to each request with a reply message
-  :doc:`Howto client/server <Howto_client_server>` doc page.
+(data).  This enables two (or more) codes to work in tandem to perform
-
+a simulation.  LAMMPS can act as either a client or server code; it
-Client/server coupling of two codes is where one code is the "client"
+does this by using the `MolSSI Driver Interface (MDI) library
-and sends request messages (data) to a "server" code.  The server
-responds to each request with a reply message.  This enables the two
-codes to work in tandem to perform a simulation.  LAMMPS can act as
-either a client or server code; it does this by using the `MolSSI
-Driver Interface (MDI) library
 <https://molssi-mdi.github.io/MDI_Library/html/index.html>`_,
 developed by the `Molecular Sciences Software Institute (MolSSI)
-<https://molssi.org>`_.
+<https://molssi.org>`_, which is supported by the :ref:`MDI <PKG-MDI>`
+package.
 
 Alternate methods for code coupling with LAMMPS are described on the
 :doc:`Howto couple <Howto_couple>` doc page.
 
-Some advantages of client/server coupling are that the two codes can run
+Some advantages of client/server coupling are that the codes can run
 as stand-alone executables; they need not be linked together.  Thus
-neither code needs to have a library interface.  This also makes it easy
+neither code needs to have a library interface.  This also makes it
-to run the two codes on different numbers of processors.  If a message
+easy to run the two codes on different numbers of processors.  If a
-protocol (format and content) is defined for a particular kind of
+message protocol (format and content) is defined for a particular kind
-simulation, then in principle any code which implements the client-side
+of simulation, then in principle any code which implements the
-protocol can be used in tandem with any code which implements the
+client-side protocol can be used in tandem with any code which
-server-side protocol.  Neither code needs to know what specific other
+implements the server-side protocol.  Neither code needs to know what
-code it is working with.
+specific other code it is working with.
 
 In MDI nomenclature, a client code is the "driver", and a server code is
 an "engine".  One driver code can communicate with one or more instances
 of one or more engine codes.  Driver and engine codes can be written in
 any language: C, C++, Fortran, Python, etc.
 
-In addition to allowing driver and engine(s) running to run as
+In addition to allowing driver and engine(s) to run as stand-alone
-stand-alone executables, MDI also enables a server code to be a
+executables, MDI also enables an engine to be a *plugin* to the client
-"plugin" to the client code.  In this scenario, server code(s) are
+code.  In this scenario, server code(s) are compiled as shared
-compiled as shared libraries, and one (or more) instances of the
+libraries, and one (or more) instances of the server are instantiated
-server are instantiated by the driver code.  If the driver code runs
+by the driver code.  If the driver code runs in parallel, it can split
-in parallel, it can split its MPI communicator into multiple
+its MPI communicator into multiple sub-communicators, and launch each
-sub-communicators, and launch each plugin engine instance on a
+plugin engine instance on a sub-communicator.  Driver processors
-sub-communicator.  Driver processors in that sub-communicator exchange
+within that sub-communicator exchange messages with the corresponding
-messages with that engine instance, and can also send MPI messages to
+engine instance, and can also send MPI messages to other processors in
-other processors in the driver.  The driver code can also destroy
+the driver.  The driver code can also destroy engine instances and
-engine instances and re-instantiate them.
+re-instantiate them.  LAMMPS can operate as either a stand-alone or
+plugin MDI engine.  When it operates as a driver, if can use either
+stand-alone or plugin MDI engines.
 
-The way that a driver communicates with an engine is by making
+The way in which an MDI driver communicates with an MDI engine is by
-MDI_Send() and MDI_Recv() calls, which are conceptually similar to
+making MDI_Send() and MDI_Recv() calls, which are conceptually similar
-MPI_Send() and MPI_Recv() calls.  Each send or receive has a string
+to MPI_Send() and MPI_Recv() calls.  Each send or receive operation
-which identifies the command name, and optionally some data, which can
+uses a string to identify the command name, and optionally some data,
-be a single value or vector of values of any data type.  Inside the
+which can be a single value or vector of values of any data type.
-MDI library, data is exchanged between the driver and engine via MPI
+Inside the MDI library, data is exchanged between the driver and
-calls or sockets.  This a run-time choice by the user.
+engine via MPI calls or sockets.  This a run-time choice by the user.
+
+----------
+
+The :ref:`MDI <PKG-MDI>` package provides a :doc:`mdi engine <mdi>`
+command which enables LAMMPS to operate as an MDI engine.  Its doc
+page explains the variety of standard and custom MDI commands which
+the LAMMPS engine recognizes and can respond to.
+
+The package also provides a :doc:`mdi plugin <mdi>` command which
+enables LAMMPS to operate as an MDI driver and load an MDI engine as a
+plugin library.
+
+The package also has a `fix mdi/aimd <fix_mdi_aimd>` command in which
+LAMMPS operates as an MDI driver to perform *ab initio* MD simulations
+in conjunction with a quantum mechanics code.  Its post_force() method
+illustrates how a driver issues MDI commands to another code.  This
+command can be used to couple to an MDI engine which is either a
+stand-alone code or a plugin library.
+
+----------
+
+The examples/mdi directory contains Python scripts and LAMMPS input
+script which use LAMMPS as either an MDI driver or engine or both.
+Three example use cases are provided:
+
+* Run ab initio MD (AIMD) using 2 instances of LAMMPS, one as driver
+  and one as an engine.  As an engine, LAMMPS is a surrogate for a
+  quantum code.
+
+* A Python script driver invokes a sequence of unrelated LAMMPS
+  calculations.  Calculations can be single-point energy/force
+  evaluations, MD runs, or energy minimizations.
+
+* Run AIMD with a Python driver code and 2 LAMMPS instances as
+  engines.  The first LAMMPS instance performs MD timestepping.  The
+  second LAMMPS instance acts as a surrogate QM code to compute
+  forces.
+
+Note that in any of these example where LAMMPS is used as an engine,
+an actual QM code (which supports MDI) could be used in its place,
+without modifying other code or scripts, except to specify the name of
+the QM code.
+
+The examples/mdi/README file explains how to launch both driver and
+engine codes so that they communicate using the MDI library via either
+MPI or sockets.
 
 -------------
 
-As an example, LAMMPS and the ``pw.x`` command from Quantum Espresso (a
+Currently there are two quantum DFT codes which have direct MDI
-suite of quantum DFT codes), can work together via the MDI library to
+support, `Quantum ESPRESSO (QE) <https://www.quantum-espresso.org/>`_
-perform an ab initio MD (AIMD) simulation, where LAMMPS runs an MD
+and `INQ <https://qsg.llnl.gov/node/101.html>`_.  There are also
-simulation and sends a message each timestep to ``pw.x`` asking it to
+several QM codes which have indirect support through QCEngine or i-PI.
-compute quantum forces on the current configuration of atoms.  Here is
+The former means they require a wrapper program (QCEngine) with MDI
-how the 2 codes are launched to communicate by MPI:
+support which writes/read files to pass data to the quantum code
+itself.  The list of QCEngine-supported and i-PI-supported quantum
+codes is on the `MDI webpage
+<https://molssi-mdi.github.io/MDI_Library/html/index.html>`_.
+
+Here is how to build QE as a stand-alone ``pw.x`` file which can be
+used in stand-alone mode:
 
 .. code-block:: bash
 
-   % mpirun -np 2 lmp_mpi -mdi "-role DRIVER -name d -method MPI" \
+   % git clone --branch mdi_plugin https://github.com/MolSSI-MDI/q-e.git <base_path>/q-e
-     -in in.aimd : -np 16 pw.x -in qe.in -mdi "-role ENGINE -name e -method MPI"
+   % build the executable pw.x, following the `QE build guide <https://gitlab.com/QEF/q-e/-/wikis/Developers/CMake-build-system>`_
 
-In this case LAMMPS runs on 2 processors (MPI tasks), ``pw.x`` runs on 16
+Here is how to build QE as a shared library which can be used in plugin mode,
-processors.
+which results in a libqemdi.so file in <base_path>/q-e/MDI/src:
-
-Here is how the 2 codes are launched to communicate by sockets:
 
 .. code-block:: bash
 
-   % mpirun -np 2 lmp_mpi -mdi "-role DRIVER -name d -method TCP -port 8021" -in in.aimd
+   % git clone --branch mdi_plugin https://github.com/MolSSI-MDI/q-e.git <base_path>/q-e
-   % mpirun -np 16 pw.x -in qe.in -mdi "-role ENGINE -name e -method TCP -port 8021 -hostname localhost"
+   % cd <base_path>/q-e
+   % ./configure --enable-parallel --enable-openmp --enable-shared FFLAGS="-fPIC" FCFLAGS="-fPIC" CFLAGS="-fPIC" foxflags="-fPIC" try_foxflags="-fPIC"
+   % make -j 4 mdi
 
-These commands could be issued in different windows on a desktop
+INQ cannot be built as a stand-alone code; it is by design a library.
-machine.  Or in the same window, if the first command is ended with
+Here is how to build INQ as a shared library which can be used in
-"&" so as to run in the background.  If "localhost" is replaced by an
+plugin mode, which results in a libinqmdi.so file in
-IP address, ``pw.x`` could be run on another machine on the same network, or
+<base_path>/inq/build/examples:
-even on another machine across the country.
 
-After both codes initialize themselves to model the same system, this is
+.. code-block:: bash
-what occurs each timestep:
 
-* LAMMPS send a ">COORDS" message to ``pw.x`` with a 3*N vector of current atom coords
+   % git clone --branch mdi --recurse-submodules https://gitlab.com/taylor-a-barnes/inq.git <base_path>/inq
-* ``pw.x`` receives the message/coords and computes quantum forces on all the atoms
+   % cd <base_path>/inq
-* LAMMPS send a "<FORCES" message to ``pw.x`` and waits for the result
+   % mkdir -p build
-* ``pw.x`` receives the message (after its computation finishes) and sends a 3*N vector of forces
+   % cd build
-* LAMMPS receives the forces and time integrates to complete a single timestep
+   % ../configure --prefix=<install_path>/install
-
+   % make -j 4
--------------
+   % make install
-
-Examples scripts for using LAMMPS as an MDI engine are in the
-examples/mdi directory.  See the README file in that directory for
-instructions on how to run the examples.
-
-.. note::
-
-  Work is underway to add commands that allow LAMMPS to be used as an
-  MDI driver, e.g. for the AIMD example discussed above.  Example
-  scripts for this usage mode will be added the same directory when
-  available.
-
-If LAMMPS is used as a stand-alone engine it should set up the system
-it will be modeling in its input script, then invoke the
-:doc:`mdi/engine <mdi_engine>` command.  This will put LAMMPS into
-"engine mode" where it waits for messages and data from the driver.
-When the driver sends an "EXIT" command, LAMMPS will exit engine mode
-and the input script will continue.
-
-If LAMMPS is used as a plugin engine it operates the same way, except
-that the driver will pass LAMMPS an input script to initialize itself.
-Upon receiving the "EXIT" command, LAMMPS will exit engine mode and the
-input script will continue.  After finishing execution of the input
-script, the instance of LAMMPS will be destroyed.
-
-LAMMPS supports the full set of MD-appropriate engine commands defined
-by the MDI library.  See the :doc:`mdi/engine <mdi_engine>` page for
-a list of these.
-
-If those commands are not sufficient for a user-developed driver to use
-LAMMPS as an engine, then new commands can be easily added.  See these
-two files which implement the definition of MDI commands and the logic
-for responding to them:
-
-* src/MDI/mdi_engine.cpp
-* src/MDI/fix_mdi_engine.cpp

doc/src/Howto_pylammps.rst

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

doc/src/Howto_structured_data.rst

@@ -21,7 +21,8 @@ YAML
    print """---
    timestep: $(step)
    pe: $(pe)
-   ke: $(ke)""" file current_state.yaml screen no
+   ke: $(ke)
+   ...""" file current_state.yaml screen no
 
 .. code-block:: yaml
    :caption: current_state.yaml
@@ -51,6 +52,62 @@ JSON
      "ke": 2.4962152903997174569
    }
 
+YAML format thermo_style output
+===============================
+
+.. versionadded:: 24Mar2022
+
+LAMMPS supports the thermo style "yaml" and for "custom" style
+thermodynamic output the format can be changed to YAML with
+:doc:`thermo_modify line yaml <thermo_modify>`.  This will produce a
+block of output in a compact YAML format - one "document" per run - of
+the following style:
+
+.. code-block:: yaml
+
+   ---
+   keywords: [Step, Temp, E_pair, E_mol, TotEng, Press, ]
+   data:
+     - [100, 0.757453103239935, -5.7585054860159, 0, -4.62236133677021, 0.207261053624721, ]
+     - [110, 0.759322359337036, -5.7614668389562, 0, -4.62251889318624, 0.194314975399602, ]
+     - [120, 0.759372342462676, -5.76149365656489, 0, -4.62247073844943, 0.191600048851267, ]
+     - [130, 0.756833027516501, -5.75777334823494, 0, -4.62255928350835, 0.208792327853067, ]
+   ...
+
+This data can be extracted and parsed from a log file using python with:
+
+.. code-block:: python
+
+   import re, yaml
+   try:
+       from yaml import CSafeLoader as Loader, CSafeDumper as Dumper
+   except ImportError:
+       from yaml import SafeLoader as Loader, SafeDumper as Dumper
+
+   docs = ""
+   with open("log.lammps") as f:
+       for line in f:
+           m = re.search(r"^(keywords:.*$|data:$|---$|\.\.\.$|  - \[.*\]$)", line)
+           if m: docs += m.group(0) + '\n'
+
+   thermo = list(yaml.load_all(docs, Loader=Loader))
+
+   print("Number of runs: ", len(thermo))
+   print(thermo[1]['keywords'][4], ' = ', thermo[1]['data'][2][4])
+
+After loading the YAML data, `thermo` is a list containing a dictionary
+for each "run" where the tag "keywords" maps to the list of thermo
+header strings and the tag "data" has a list of lists where the outer
+list represents the lines of output and the inner list the values of the
+columns matching the header keywords for that step.  The second print()
+command for example will print the header string for the fifth keyword
+of the second run and the corresponding value for the third output line
+of that run:
+
+.. parsed-literal::
+
+   Number of runs:  2
+   TotEng  =  -4.62140097780047
 
 Writing continuous data during a simulation
 ===========================================

doc/src/Install_git.rst

@@ -165,5 +165,4 @@ changed.  How to do this depends on the build system you are using.
    URL "git@github.com:lammps/lammps.git".
 
 The LAMMPS GitHub project is currently managed by Axel Kohlmeyer
-(Temple U, akohlmey at gmail.com) and Richard Berger (Temple U,
+(Temple U, akohlmey at gmail.com).
-richard.berger at temple.edu).

doc/src/Install_mac.rst

@@ -5,7 +5,7 @@ LAMMPS can be downloaded, built, and configured for OS X on a Mac with
 `Homebrew <homebrew_>`_.  (Alternatively, see the install instructions for
 :doc:`Download an executable via Conda <Install_conda>`.)  The following LAMMPS
 packages are unavailable at this time because of additional needs not yet met:
-GPU, KOKKOS, LATTE, MSCG, MESSAGE, MPIIO POEMS VORONOI.
+GPU, KOKKOS, LATTE, MSCG, MPIIO, POEMS, VORONOI.
 
 After installing Homebrew, you can install LAMMPS on your system with
 the following commands:

doc/src/Install_tarball.rst

@@ -6,7 +6,7 @@ of the `LAMMPS website <lws_>`_.
 
 .. _download: https://www.lammps.org/download.html
 .. _bug: https://www.lammps.org/bug.html
-.. _older: https://www.lammps.org/tars
+.. _older: https://download.lammps.org/tars/
 .. _lws: https://www.lammps.org
 
 You have two choices of tarballs, either the most recent stable

doc/src/Intro_authors.rst

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

doc/src/Intro_citing.rst

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

doc/src/Intro_website.rst

@@ -20,7 +20,6 @@ available online are listed below.
 * `Glossary of terms relevant to LAMMPS <https://www.lammps.org/glossary.html>`_
 * `LAMMPS highlights with images <https://www.lammps.org/pictures.html>`_
 * `LAMMPS highlights with movies <https://www.lammps.org/movies.html>`_
-* `Mailing list <https://www.lammps.org/mail.html>`_
 * `LAMMPS forum <https://www.lammps.org/forum.html>`_
 * `Workshops <https://www.lammps.org/workshops.html>`_
 * `Tutorials <https://www.lammps.org/tutorials.html>`_

doc/src/Library_utility.rst

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

doc/src/Manual.rst

@@ -14,11 +14,11 @@ LAMMPS is an open-source code, distributed freely under the terms of
 the GNU Public License Version 2 (GPLv2).
 
 The `LAMMPS website <lws_>`_ has a variety of information about the
-code.  It includes links to an on-line version of this manual, a
+code.  It includes links to an on-line version of this manual, an
-`mailing list <https://www.lammps.org/mail.html>`_ and
+`online forum <https://www.lammps.org/forum.html>`_ where users can post
-`online forum <https://www.lammps.org/forum.html>`_  where users can
+questions and discuss LAMMPS, and a `GitHub site
-post questions, and a `GitHub site <https://github.com/lammps/lammps>`_
+<https://github.com/lammps/lammps>`_ where all LAMMPS development is
-where all LAMMPS development is coordinated.
+coordinated.
 
 ----------
 

doc/src/Modify.rst

@@ -1,16 +1,17 @@
 Modifying & extending LAMMPS
 ****************************
 
-LAMMPS is designed in a modular fashion so as to be easy to modify and
+LAMMPS is designed in a modular fashion and to be easy to modify or
 extend with new functionality.  In fact, about 95% of its source code
-is add-on files.  These doc pages give basic instructions on how to do
+are optional.  The following pages give basic instructions on what
-this.
+is required when adding new styles of different kinds to LAMMPS.
 
-If you add a new feature to LAMMPS and think it will be of interest to
+If you add a new feature to LAMMPS and think it will be of general
-general users, we encourage you to submit it for inclusion in LAMMPS
+interest to other users, we encourage you to submit it for inclusion in
-as a pull request on our `GitHub site <https://github.com/lammps/lammps>`_,
+LAMMPS as a pull request on our `GitHub site
-after reading about :doc:`how to prepare your code for submission <Modify_contribute>`
+<https://github.com/lammps/lammps>`_, after reading about :doc:`how to
-and :doc:`the style requirements and recommendations <Modify_style>`.
+prepare your code for submission <Modify_contribute>` and :doc:`the
+style requirements and recommendations <Modify_style>`.
 
 .. toctree::
    :maxdepth: 1

doc/src/Modify_atom.rst

@@ -9,34 +9,34 @@ A new atom style can be created if one of the existing atom styles
 does not define all the attributes you need to store and communicate
 with atoms.
 
-Atom_vec_atomic.cpp is the simplest example of an atom style.
+The file ``atom_vec_atomic.cpp`` is the simplest example of an atom style.
 Examining the code for others will make these instructions more clear.
 
-Note that the :doc:`atom style hybrid <atom_style>` command can be
+Note that the :doc:`atom style hybrid <atom_style>` command can be used
-used to define atoms or particles which have the union of properties
+to define atoms or particles which have the union of properties of
-of individual styles.  Also the :doc:`fix property/atom <fix_property_atom>`
+individual styles.  Also the :doc:`fix property/atom
-command can be used to add a single property (e.g. charge
+<fix_property_atom>` command can be used to add a single property
-or a molecule ID) to a style that does not have it.  It can also be
+(e.g. charge or a molecule ID) to a style that does not have it.  It can
-used to add custom properties to an atom, with options to communicate
+also be used to add custom properties to an atom, with options to
-them with ghost atoms or read them from a data file.  Other LAMMPS
+communicate them with ghost atoms or read them from a data file.  Other
-commands can access these custom properties, as can new pair, fix,
+LAMMPS commands can access these custom properties, as can new pair,
-compute styles that are written to work with these properties.  For
+fix, compute styles that are written to work with these properties.  For
 example, the :doc:`set <set>` command can be used to set the values of
 custom per-atom properties from an input script.  All of these methods
-are less work than writing code for a new atom style.
+are less work than writing and testing(!) code for a new atom style.
 
 If you follow these directions your new style will automatically work
 in tandem with others via the :doc:`atom_style hybrid <atom_style>`
 command.
 
-The first step is to define a set of strings in the constructor of the
+The first step is to define a set of string lists in the constructor of
-new derived class.  Each string will have zero or more space-separated
+the new derived class.  Each list will have zero or more comma-separated
-variable names which are identical to those used in the atom.h header
+strings that correspond to the variable names used in the ``atom.h``
-file for per-atom properties.  Note that some represent per-atom
+header file for per-atom properties.  Note that some represent per-atom
 vectors (q, molecule) while other are per-atom arrays (x,v).  For all
-but the last 2 strings you do not need to specify any of
+but the last two lists you do not need to specify any of
 (id,type,x,v,f).  Those are included automatically as needed in the
-other strings.
+other lists.
 
 .. list-table::
 
@@ -65,16 +65,16 @@ other strings.
    * - fields_data_vel
      - list of properties (in order) in the Velocities section of a data file, as read by :doc:`read_data <read_data>`
 
-In these strings you can list variable names which LAMMPS already
+In these lists you can list variable names which LAMMPS already defines
-defines (in some other atom style), or you can create new variable
+(in some other atom style), or you can create new variable names.  You
-names.  You should not re-use a LAMMPS variable for something with
+should not re-use a LAMMPS variable in your atom style that is used for
-different meaning in your atom style.  If the meaning is related, but
+something with a different meaning in another atom style.  If the
-interpreted differently by your atom style, then using the same
+meaning is related, but interpreted differently by your atom style, then
-variable name means a user should not use your style and the other
+using the same variable name means a user must not use your style and
-style together in a :doc:`atom_style hybrid <atom_style>` command.
+the other style together in a :doc:`atom_style hybrid <atom_style>`
-Because there will only be one value of the variable and different
+command.  Because there will only be one value of the variable and
-parts of LAMMPS will then likely use it differently.  LAMMPS has
+different parts of LAMMPS will then likely use it differently.  LAMMPS
-no way of checking for this.
+has no way of checking for this.
 
 If you are defining new variable names then make them descriptive and
 unique to your new atom style.  For example choosing "e" for energy is
@@ -85,32 +85,31 @@ If any of the variable names in your new atom style do not exist in
 LAMMPS, you need to add them to the src/atom.h and atom.cpp files.
 
 Search for the word "customize" or "customization" in these 2 files to
-see where to add your variable.  Adding a flag to the 2nd
+see where to add your variable.  Adding a flag to the 2nd customization
-customization section in atom.h is only necessary if your code (e.g. a
+section in ``atom.h`` is only necessary if your code (e.g. a pair style)
-pair style) needs to check that a per-atom property is defined.  These
+needs to check that a per-atom property is defined.  These flags should
-flags should also be set in the constructor of the atom style child
+also be set in the constructor of the atom style child class.
-class.
 
-In atom.cpp, aside from the constructor and destructor, there are 3
+In ``atom.cpp``, aside from the constructor and destructor, there are 3
 methods that a new variable name or flag needs to be added to.
 
-In Atom::peratom_create() when using the add_peratom() method, a
+In ``Atom::peratom_create()`` when using the ``Atom::add_peratom()``
-final length argument of 0 is for per-atom vectors, a length > 1 is
+method, a cols argument of 0 is for per-atom vectors, a length >
-for per-atom arrays.  Note the use of an extra per-thread flag and the
+1 is for per-atom arrays.  Note the use of the extra per-thread flag and
-add_peratom_vary() method when last dimension of the array is
+the add_peratom_vary() method when last dimension of the array is
 variable-length.
 
-Adding the variable name to Atom::extract() enable the per-atom data
+Adding the variable name to Atom::extract() enables the per-atom data
 to be accessed through the :doc:`LAMMPS library interface
 <Howto_library>` by a calling code, including from :doc:`Python
 <Python_head>`.
 
 The constructor of the new atom style will also typically set a few
-flags which are defined at the top of atom_vec.h.  If these are
+flags which are defined at the top of ``atom_vec.h``.  If these are
 unclear, see how other atom styles use them.
 
-The grow_pointers() method is also required to make
+The grow_pointers() method is also required to make a copy of peratom
-a copy of peratom data pointers, as explained in the code.
+data pointers, as explained in the code.
 
 There are a number of other optional methods which your atom style can
 implement.  These are only needed if you need to do something

doc/src/Modify_contribute.rst

@@ -27,11 +27,10 @@ join the `LAMMPS developers on Slack <https://lammps.slack.com>`_.  This
 slack work space is by invitation only.  Thus for access, please send an
 e-mail to ``slack@lammps.org`` explaining what part of LAMMPS you are
 working on.  Only discussions related to LAMMPS development are
-tolerated in that work space, so this is **NOT** for people that look for
+tolerated in that work space, so this is **NOT** for people that look
-help with compiling, installing, or using LAMMPS.  Please post a message
+for help with compiling, installing, or using LAMMPS.  Please post a
-to the `lammps-users mailing list <https://www.lammps.org/mail.html>`_
+message to the `LAMMPS forum <https://www.lammps.org/forum.html>`_ for
-or the `LAMMPS forum <https://www.lammps.org/forum.html>`_ for those
+those purposes.
-purposes.
 
 Packages versus individual files
 --------------------------------

doc/src/Modify_overview.rst

@@ -1,13 +1,14 @@
 Overview
 ========
 
-The best way to add a new feature to LAMMPS is to find a similar
+The best way to add a new feature to LAMMPS is to find a similar feature
-feature and look at the corresponding source and header files to figure
+and look at the corresponding source and header files to figure out what
-out what it does.  You will need some knowledge of C++ to be able to
+it does.  You will need some knowledge of C++ to be able to understand
-understand the high-level structure of LAMMPS and its class
+the high-level structure of LAMMPS and its class organization, but
-organization, but functions (class methods) that do actual
+functions (class methods) that do actual computations are mostly written
-computations are written in vanilla C-style code and operate on simple
+in C-style code and operate on simple C-style data structures (vectors
-C-style data structures (vectors and arrays).
+and arrays).  A high-level overview of the programming style choices in
+LAMMPS is :doc:`given elsewhere <Developer_code_design>`.
 
 Most of the new features described on the :doc:`Modify <Modify>` doc
 page require you to write a new C++ derived class (except for exceptions

doc/src/Modify_pair.rst

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

doc/src/Modify_style.rst

@@ -223,6 +223,13 @@ and readable by all and no executable permissions.  Executable
 permissions (0755) should only be on shell scripts or python or similar
 scripts for interpreted script languages.
 
+You can check for these issues with the python scripts in the
+:ref:`"tools/coding_standard" <coding_standard>` folder.  When run
+normally with a source file or a source folder as argument, they will
+list all non-conforming lines.  By adding the `-f` flag to the command
+line, they will modify the flagged files to try removing the detected
+issues.
+
 Indentation and Placement of Braces (strongly preferred)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -240,6 +247,53 @@ reformatting from clang-format yields undesirable output may be
 protected with placing a pair `// clang-format off` and `// clang-format
 on` comments around that block.
 
+Error or warning messages and explanations (preferred)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionchanged:: 27Apr2022
+
+Starting with LAMMPS version 27 April 2022 the LAMMPS developers have
+agreed on a new policy for error and warning messages.
+
+Previously, all error and warning strings were supposed to be listed in
+the class header files with an explanation.  Those would then be
+regularly "harvested" and transferred to alphabetically sorted lists in
+the manual.  To avoid excessively long lists and to reduce effort, this
+came with a requirement to have rather generic error messages (e.g.
+"Illegal ... command").  To identify the specific cause, the name of the
+source file and the line number of the error location would be printed,
+so that one could look up the cause by reading the source code.
+
+The new policy encourages more specific error messages that ideally
+indicate the cause directly and no further lookup would be needed.
+This is aided by using the `{fmt} library <https://fmt.dev>`_ to convert
+the Error class commands so that they take a variable number of arguments
+and error text will be treated like a {fmt} syntax format string.
+Error messages should still kept to a single line or two lines at the most.
+
+For more complex explanations or errors that have multiple possible
+reasons, a paragraph should be added to the `Error_details` page with an
+error code reference (e.g. ``.. _err0001:``) then the utility function
+:cpp:func:`utils::errorurl() <LAMMPS_NS::utils::errorurl>` can be used
+to generate an URL that will directly lead to that paragraph.  An error
+for missing arguments can be easily generated using the
+:cpp:func:`utils::missing_cmd_args()
+<LAMMPS_NS::utils::missing_cmd_args>` convenience function.
+
+The transformation of existing LAMMPS code to this new scheme is ongoing
+and - given the size of the LAMMPS source code - will take a significant
+amount of time until completion.  However, for new code following the
+new approach is strongly preferred.  The expectation is that the new
+scheme will make it easier for LAMMPS users, developers, and
+maintainers.
+
+An example for this approach would be the
+``src/read_data.cpp`` and ``src/atom.cpp`` files that implement the
+:doc:`read_data <read_data>` and :doc:`atom_modify <atom_modify>`
+commands and that may create :ref:`"Unknown identifier in data file" <err0001>`
+errors that seem difficult to debug for users because they may have
+one of multiple possible reasons, and thus require some additional explanations.
+
 Programming language standards (required)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -250,9 +304,11 @@ keep the code readable to programmers that have limited C++ programming
 experience.  C++ constructs are acceptable when they help improving the
 readability and reliability of the code, e.g. when using the
 `std::string` class instead of manipulating pointers and calling the
-string functions of the C library.  In addition and number of convenient
+string functions of the C library.  In addition a collection of
-:doc:`utility functions and classes <Developer_utils>` for recurring
+convenient :doc:`utility functions and classes <Developer_utils>` for
-tasks are provided.
+recurring tasks and a collection of
+:doc:`platform neutral functions <Developer_platform>` for improved
+portability are provided.
 
 Included Fortran code has to be compatible with the Fortran 2003
 standard.  Python code must be compatible with Python 3.5.  Large parts
@@ -261,10 +317,11 @@ compatible with Python 2.7.  Compatibility with Python 2.7 is
 desirable, but compatibility with Python 3.5 is **required**.
 
 Compatibility with these older programming language standards is very
-important to maintain portability, especially with HPC cluster
+important to maintain portability and availability of LAMMPS on many
-environments, which tend to be running older software stacks and LAMMPS
+platforms.  This applies especially to HPC cluster environments, which
-users may be required to use those older tools or not have the option to
+tend to be running older software stacks and LAMMPS users may be
-install newer compilers.
+required to use those older tools for access to advanced hardware
+features or not have the option to install newer compilers or libraries.
 
 Programming conventions (varied)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -305,6 +362,40 @@ you are uncertain, please ask.
   FILE pointers and only be done on MPI rank 0.  Use the :cpp:func:`utils::logmesg`
   convenience function where possible.
 
+- Usage of C++11 `virtual`, `override`, `final` keywords: Please follow the
+  `C++ Core Guideline C.128 <https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rh-override>`_.
+  That means, you should only use `virtual` to declare a new virtual
+  function, `override` to indicate you are overriding an existing virtual
+  function, and `final` to prevent any further overriding.
+
+- Trivial destructors: Prefer not writing destructors when they are empty and `default`.
+
+  .. code-block:: c++
+
+     // don't write destructors for A or B like this
+     class A : protected Pointers {
+      public:
+        A();
+        ~A() override {}
+     };
+
+     class B : protected Pointers {
+      public:
+        B();
+        ~B() override = default;
+     };
+
+     // instead, let the compiler create the implicit default destructor by not writing it
+     class A : protected Pointers {
+      public:
+        A();
+     };
+
+     class B : protected Pointers {
+      public:
+        B();
+     };
+
 - Header files, especially those defining a "style", should only use
   the absolute minimum number of include files and **must not** contain
   any ``using`` statements. Typically that would be only the header for

doc/src/Modify_thermo.rst

@@ -1,27 +1,54 @@
 Thermodynamic output options
 ============================
 
-There is one class that computes and prints thermodynamic information
+The ``Thermo`` class computes and prints thermodynamic information to
-to the screen and log file; see the file thermo.cpp.
+the screen and log file; see the files ``thermo.cpp`` and ``thermo.h``.
 
-There are two styles defined in thermo.cpp: "one" and "multi".  There
+There are four styles defined in ``thermo.cpp``: "one", "multi", "yaml",
-is also a flexible "custom" style which allows the user to explicitly
+and "custom".  The "custom" style allows the user to explicitly list
-list keywords for quantities to print when thermodynamic info is
+keywords for individual quantities to print when thermodynamic output is
-output.  See the :doc:`thermo_style <thermo_style>` command for a list
+generated.  The others have a fixed list of keywords.  See the
-of defined quantities.
+:doc:`thermo_style <thermo_style>` command for a list of available
+quantities.  The formatting of the "custom" style defaults to the "one"
+style, but can be adapted using :doc:`thermo_modify line <thermo_modify>`.
 
-The thermo styles (one, multi, etc) are simply lists of keywords.
+The thermo styles (one, multi, etc) are defined by lists of keywords
-Adding a new style thus only requires defining a new list of keywords.
+with associated formats for integer and floating point numbers and
-Search for the word "customize" with references to "thermo style" in
+identified but an enumerator constant.  Adding a new style thus mostly
-thermo.cpp to see the two locations where code will need to be added.
+requires defining a new list of keywords and the associated formats and
+then inserting the required output processing where the enumerators are
+identified.  Search for the word "CUSTOMIZATION" with references to
+"thermo style" in the ``thermo.cpp`` file to see the locations where
+code will need to be added.  The member function ``Thermo::header()``
+prints output at the very beginning of a thermodynamic output block and
+can be used to print column headers or other front matter.  The member
+function ``Thermo::footer()`` prints output at the end of a
+thermodynamic output block.  The formatting of the output is done by
+assembling a "line" (which may span multiple lines if the style inserts
+newline characters ("\n" as in the "multi" style).
 
-New keywords can also be added to thermo.cpp to compute new quantities
+New thermodynamic keywords can also be added to ``thermo.cpp`` to
-for output.  Search for the word "customize" with references to
+compute new quantities for output.  Search for the word "CUSTOMIZATION"
-"keyword" in thermo.cpp to see the several locations where code will
+with references to "keyword" in ``thermo.cpp`` to see the several
-need to be added.
+locations where code will need to be added.  Effectively, you need to
+define a member function that computes the property, add an if statement
+in ``Thermo::parse_fields()`` where the corresponding header string for
+the keyword and the function pointer is registered by calling the
+``Thermo::addfield()`` method, and add an if statement in
+``Thermo::evaluate_keyword()`` which is called from the ``Variable``
+class when a thermo keyword is encountered.
 
-Note that the :doc:`thermo_style custom <thermo_style>` command already allows
+.. note::
-for thermo output of quantities calculated by :doc:`fixes <fix>`,
+
-:doc:`computes <compute>`, and :doc:`variables <variable>`.  Thus, it may
+   The third argument to ``Thermo::addfield()`` is a flag indicating
-be simpler to compute what you wish via one of those constructs, than
+   whether the function for the keyword computes a floating point
-by adding a new keyword to the thermo command.
+   (FLOAT), regular integer (INT), or big integer (BIGINT) value.  This
+   information is used for formatting the thermodynamic output.  Inside
+   the function the result must then be stored either in the ``dvalue``,
+   ``ivalue`` or ``bivalue`` member variable, respectively.
+
+Since the :doc:`thermo_style custom <thermo_style>` command allows to
+use output of quantities calculated by :doc:`fixes <fix>`,
+:doc:`computes <compute>`, and :doc:`variables <variable>`, it may often
+be simpler to compute what you wish via one of those constructs, rather
+than by adding a new keyword to the thermo_style command.

doc/src/Modify_variable.rst

@@ -1,8 +1,8 @@
 Variable options
 ================
 
-There is one class that computes and stores :doc:`variable <variable>`
+The ``Variable`` class computes and stores :doc:`variable <variable>`
-information in LAMMPS; see the file variable.cpp.  The value
+information in LAMMPS; see the file ``variable.cpp``.  The value
 associated with a variable can be periodically printed to the screen
 via the :doc:`print <print>`, :doc:`fix print <fix_print>`, or
 :doc:`thermo_style custom <thermo_style>` commands.  Variables of style
@@ -19,21 +19,22 @@ of arguments:
    compute values = c_mytemp[0], c_thermo_press[3], ...
 
 Adding keywords for the :doc:`thermo_style custom <thermo_style>`
-command (which can then be accessed by variables) is discussed on the
+command (which can then be accessed by variables) is discussed in the
-:doc:`Modify thermo <Modify_thermo>` doc page.
+:doc:`Modify thermo <Modify_thermo>` documentation.
 
 Adding a new math function of one or two arguments can be done by
-editing one section of the Variable::evaluate() method.  Search for
+editing one section of the ``Variable::evaluate()`` method.  Search for
 the word "customize" to find the appropriate location.
 
 Adding a new group function can be done by editing one section of the
-Variable::evaluate() method.  Search for the word "customize" to find
+``Variable::evaluate()`` method.  Search for the word "customize" to
-the appropriate location.  You may need to add a new method to the
+find the appropriate location.  You may need to add a new method to the
-Group class as well (see the group.cpp file).
+Group class as well (see the ``group.cpp`` file).
 
 Accessing a new atom-based vector can be done by editing one section
 of the Variable::evaluate() method.  Search for the word "customize"
 to find the appropriate location.
 
 Adding new :doc:`compute styles <compute>` (whose calculated values can
-then be accessed by variables) is discussed on the :doc:`Modify compute <Modify_compute>` doc page.
+then be accessed by variables) is discussed in the :doc:`Modify compute
+<Modify_compute>` documentation.

doc/src/Packages_details.rst

@@ -9,7 +9,7 @@ gives links to documentation, example scripts, and pictures/movies (if
 available) that illustrate use of the package.
 
 The majority of packages can be included in a LAMMPS build with a
-single setting (``-D PGK_<NAME>=on`` for CMake) or command
+single setting (``-D PKG_<NAME>=on`` for CMake) or command
 (``make yes-<name>`` for make).  See the :doc:`Build package <Build_package>`
 page for more info.  A few packages may require additional steps;
 this is indicated in the descriptions below.  The :doc:`Build extras <Build_extras>`
@@ -32,6 +32,7 @@ page gives those details.
    * :ref:`AWPMD <PKG-AWPMD>`
    * :ref:`BOCS <PKG-BOCS>`
    * :ref:`BODY <PKG-BODY>`
+   * :ref:`BPM <PKG-BPM>`
    * :ref:`BROWNIAN <PKG-BROWNIAN>`
    * :ref:`CG-DNA <PKG-CG-DNA>`
    * :ref:`CG-SDK <PKG-CG-SDK>`
@@ -72,7 +73,6 @@ page gives those details.
    * :ref:`MDI <PKG-MDI>`
    * :ref:`MEAM <PKG-MEAM>`
    * :ref:`MESONT <PKG-MESONT>`
-   * :ref:`MESSAGE <PKG-MESSAGE>`
    * :ref:`MGPT <PKG-MGPT>`
    * :ref:`MISC <PKG-MISC>`
    * :ref:`ML-HDNNP <PKG-ML-HDNNP>`
@@ -284,6 +284,33 @@ overview.
 
 ----------
 
+.. _PKG-BPM:
+
+BPM package
+------------
+
+**Contents:**
+
+Pair styles, bond styles, fixes, and computes for bonded particle
+models for mesoscale simulations of solids and fracture.  See the
+:doc:`Howto bpm <Howto_bpm>` page for an overview.
+
+**Authors:** Joel T. Clemmer (Sandia National Labs)
+
+**Supporting info:**
+
+* src/BPM filenames -> commands
+* :doc:`Howto_bpm <Howto_bpm>`
+* :doc:`atom_style bpm/sphere <atom_style>`
+* :doc:`bond_style bpm/rotational <bond_bpm_rotational>`
+* :doc:`bond_style bpm/spring <bond_bpm_spring>`
+* :doc:`compute nbond/atom <compute_nbond_atom>`
+* :doc:`fix nve/bpm/sphere <fix_nve_bpm_sphere>`
+* :doc:`pair_style bpm/spring <pair_bpm_spring>`
+* examples/bpm
+
+----------
+
 .. _PKG-BROWNIAN:
 
 BROWNIAN package
@@ -529,8 +556,20 @@ To use this package, also the :ref:`KSPACE <PKG-KSPACE>` and
 **Supporting info:**
 
 * src/DIELECTRIC: filenames -> commands
+* :doc:`atom_style dielectric <atom_style>`
+* :doc:`pair_style coul/cut/dielectric <pair_dielectric>`
+* :doc:`pair_style coul/long/dielectric <pair_dielectric>`
+* :doc:`pair_style lj/cut/coul/cut/dielectric <pair_dielectric>`
+* :doc:`pair_style lj/cut/coul/debye/dielectric <pair_dielectric>`
+* :doc:`pair_style lj/cut/coul/long/dielectric <pair_dielectric>`
+* :doc:`pair_style lj/cut/coul/msm/dielectric <pair_dielectric>`
+* :doc:`pair_style pppm/dielectric <kspace_style>`
+* :doc:`pair_style pppm/disp/dielectric <kspace_style>`
+* :doc:`pair_style msm/dielectric <kspace_style>`
+* :doc:`fix_style polarize/bem/icc <fix_polarize>`
+* :doc:`fix_style polarize/bem/gmres <fix_polarize>`
+* :doc:`fix_style polarize/functional <fix_polarize>`
 * :doc:`compute efield/atom  <compute_efield_atom>`
-* TODO: add all styles
 * examples/PACKAGES/dielectric
 
 ----------
@@ -1396,17 +1435,25 @@ MDI package
 
 **Contents:**
 
-A LAMMPS command and fix to allow client-server coupling of LAMMPS to
+A LAMMPS command and fixes to allow client-server coupling of LAMMPS
-other atomic or molecular simulation codes via the `MolSSI Driver Interface
+to other atomic or molecular simulation codes or materials modeling
+workflows via the `MolSSI Driver Interface
 (MDI) library <https://molssi-mdi.github.io/MDI_Library/html/index.html>`_.
 
 **Author:** Taylor Barnes - MolSSI, taylor.a.barnes at gmail.com
 
+**Install:**
+
+This package has :ref:`specific installation instructions <mdi>` on
+the :doc:`Build extras <Build_extras>` page.
+
 **Supporting info:**
 
 * src/MDI/README
-* :doc:`mdi/engine <mdi_engine>`
+* lib/mdi/README
-* :doc:`fix mdi/engine <fix_mdi_engine>`
+* :doc:`Howto MDI <Howto_mdi>`
+* :doc:`mdi <mdi>`
+* :doc:`fix mdi/aimd <fix_mdi_aimd>`
 * examples/PACKAGES/mdi
 
 ----------
@@ -1483,32 +1530,6 @@ Philipp Kloza (U Cambridge)
 
 ----------
 
-.. _PKG-MESSAGE:
-
-MESSAGE package
----------------
-
-**Contents:**
-
-Commands to use LAMMPS as either a client or server and couple it to
-another application.
-
-**Install:**
-
-This package has :ref:`specific installation instructions <message>` on the :doc:`Build extras <Build_extras>` page.
-
-**Supporting info:**
-
-* src/MESSAGE: filenames -> commands
-* lib/message/README
-* :doc:`message <message>`
-* :doc:`fix client/md <fix_client_md>`
-* :doc:`server md <server_md>`
-* :doc:`server mc <server_mc>`
-* examples/message
-
-----------
-
 .. _PKG-MGPT:
 
 MGPT package
@@ -1564,7 +1585,6 @@ listing, "ls src/MISC", to see the list of commands.
 * :doc:`pair_style list <pair_list>`
 * :doc:`pair_style srp <pair_srp>`
 * :doc:`pair_style tracker <pair_tracker>`
-* :doc:`fix pair/tracker <fix_pair_tracker>`
 
 ----------
 
@@ -1880,6 +1900,12 @@ MPIIO library.  It adds :doc:`dump styles <dump>` with a "mpiio" in
 their style name.  Restart files with an ".mpiio" suffix are also
 written and read in parallel.
 
+.. warning::
+
+   The MPIIO package is currently unmaintained and has become
+   unreliable. Use with caution.
+
+
 **Install:**
 
 The MPIIO package requires that LAMMPS is build in :ref:`MPI parallel mode <serial>`.
@@ -2148,6 +2174,11 @@ A :doc:`plugin <plugin>` command that can load and unload several
 kind of styles in LAMMPS from shared object files at runtime without
 having to recompile and relink LAMMPS.
 
+When the environment variable ``LAMMPS_PLUGIN_PATH`` is set, then LAMMPS
+will search the directory (or directories) listed in this path for files
+with names that end in ``plugin.so`` (e.g. ``helloplugin.so``) and will
+try to load the contained plugins automatically at start-up.
+
 **Authors:** Axel Kohlmeyer (Temple U)
 
 **Supporting info:**

doc/src/Packages_list.rst

@@ -58,6 +58,11 @@ whether an extra library is needed to build and use the package:
      - :doc:`Howto body <Howto_body>`
      - body
      - no
+   * - :ref:`BPM <PKG-BPM>`
+     - bonded particle models
+     - :doc:`Howto bpm <Howto_bpm>`
+     - bpm
+     - no
    * - :ref:`BROWNIAN <PKG-BROWNIAN>`
      - Brownian dynamics, self-propelled particles
      - :doc:`fix brownian <fix_brownian>`, :doc:`fix propel/self <fix_propel_self>`
@@ -244,7 +249,7 @@ whether an extra library is needed to build and use the package:
      - n/a
      - no
    * - :ref:`MDI <PKG-MDI>`
-     - client-server coupling
+     - client-server code coupling
      - :doc:`MDI Howto <Howto_mdi>`
      - PACKAGES/mdi
      - ext
@@ -258,11 +263,6 @@ whether an extra library is needed to build and use the package:
      - pair styles :doc:`mesont/tpm <pair_mesont_tpm>`, :doc:`mesocnt <pair_mesocnt>`
      - PACKAGES/mesont
      - int
-   * - :ref:`MESSAGE <PKG-MESSAGE>`
-     - client/server messaging
-     - :doc:`message <message>`
-     - message
-     - int
    * - :ref:`MGPT <PKG-MGPT>`
      - fast MGPT multi-ion potentials
      - :doc:`pair_style mgpt <pair_mgpt>`

doc/src/Python_install.rst

@@ -25,11 +25,10 @@ Installing the LAMMPS Python Module and Shared Library
 ======================================================
 
 Making LAMMPS usable within Python and vice versa requires putting the
-LAMMPS Python package (``lammps``) into a location where the
+LAMMPS Python package (``lammps``) into a location where the Python
-Python interpreter can find it and installing the LAMMPS shared library
+interpreter can find it and installing the LAMMPS shared library into a
-into a folder that the dynamic loader searches or inside of the installed
+folder that the dynamic loader searches or inside of the installed
-``lammps`` package folder.  There are multiple ways to achieve
+``lammps`` package folder.  There are multiple ways to achieve this.
-this.
 
 #. Do a full LAMMPS installation of libraries, executables, selected
    headers, documentation (if enabled), and supporting files (only
@@ -159,38 +158,52 @@ this.
 
          make install-python
 
-      This will try to install (only) the shared library and the Python
+      This will try to build a so-called (binary) 'wheel', a compressed
-      package into a system folder and if that fails (due to missing
+      binary python package and then install it with the python package
-      write permissions) will instead do the installation to a user
+      manager 'pip'.  Installation will be attempted into a system-wide
-      folder under ``$HOME/.local``.  For a system-wide installation you
+      ``site-packages`` folder and if that fails into the corresponding
+      folder in the user's home directory.  For a system-wide installation you
       would have to gain superuser privilege, e.g. though ``sudo``
 
-      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+      +------------------------+----------------------------------------------------------+-------------------------------------------------------------+
       | File                   | Location                                                 | Notes                                                       |
-      +========================+=================================================================+=============================================================+
+      +========================+==========================================================+=============================================================+
-      | LAMMPS Python package  | * ``$HOME/.local/lib/pythonX.Y/site-packages/lammps`` (32bit)   | ``X.Y`` depends on the installed Python version             |
+      | LAMMPS Python package  | * ``$HOME/.local/lib/pythonX.Y/site-packages/lammps``    | ``X.Y`` depends on the installed Python version             |
-      |                        | * ``$HOME/.local/lib64/pythonX.Y/site-packages/lammps`` (64bit) |                                                             |
+      +------------------------+----------------------------------------------------------+-------------------------------------------------------------+
-      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+      | LAMMPS shared library  | * ``$HOME/.local/lib/pythonX.Y/site-packages/lammps``    | ``X.Y`` depends on the installed Python version             |
-      | LAMMPS shared library  | * ``$HOME/.local/lib/pythonX.Y/site-packages/lammps`` (32bit)   | ``X.Y`` depends on the installed Python version             |
+      +------------------------+----------------------------------------------------------+-------------------------------------------------------------+
-      |                        | * ``$HOME/.local/lib64/pythonX.Y/site-packages/lammps`` (64bit) |                                                             |
-      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
 
       For a system-wide installation those folders would then become.
 
-      +------------------------+---------------------------------------------------------+-------------------------------------------------------------+
+      +------------------------+-------------------------------------------------+-------------------------------------------------------------+
       | File                   | Location                                        | Notes                                                       |
-      +========================+=========================================================+=============================================================+
+      +========================+=================================================+=============================================================+
-      | LAMMPS Python package  | * ``/usr/lib/pythonX.Y/site-packages/lammps`` (32bit)   | ``X.Y`` depends on the installed Python version             |
+      | LAMMPS Python package  | * ``/usr/lib/pythonX.Y/site-packages/lammps``   | ``X.Y`` depends on the installed Python version             |
-      |                        | * ``/usr/lib64/pythonX.Y/site-packages/lammps`` (64bit) |                                                             |
+      +------------------------+-------------------------------------------------+-------------------------------------------------------------+
-      +------------------------+---------------------------------------------------------+-------------------------------------------------------------+
+      | LAMMPS shared library  | * ``/usr/lib/pythonX.Y/site-packages/lammps``   | ``X.Y`` depends on the installed Python version             |
-      | LAMMPS shared library  | * ``/usr/lib/pythonX.Y/site-packages/lammps`` (32bit)   | ``X.Y`` depends on the installed Python version             |
+      +------------------------+-------------------------------------------------+-------------------------------------------------------------+
-      |                        | * ``/usr/lib64/pythonX.Y/site-packages/lammps`` (64bit) |                                                             |
-      +------------------------+---------------------------------------------------------+-------------------------------------------------------------+
 
       No environment variables need to be set for those, as those
       folders are searched by default by Python or the LAMMPS Python
       package.
 
+      .. versionchanged:: 24Mar2022
+
+      .. note::
+
+            If there is an existing installation of the LAMMPS python
+            module, ``make install-python`` will try to update it.
+            However, that will fail if the older version of the module
+            was installed by LAMMPS versions until 17Feb2022.  Those
+            were using the distutils package, which does not create a
+            "manifest" that allows a clean uninstall.  The ``make
+            install-python`` command will always produce a
+            lammps-<version>-<python>-<abi>-<os>-<arch>.whl file (the
+            'wheel'). And this file can be later installed directly with
+            ``python -m pip install <wheel file>.whl`` without having to
+            type ``make install-python`` again and repeating the build
+            step, too.
+
       For the traditional make process you can override the python
       version to version x.y when calling ``make`` with
       ``PYTHON=pythonX.Y``.  For a CMake based compilation this choice
@@ -201,16 +214,12 @@ this.
 
       .. code-block:: bash
 
-         $ python install.py -p <python package> -l <shared library> -v <version.h file> [-d <pydir>]
+         $ python install.py -p <python package> -l <shared library> [-n]
 
       * The ``-p`` flag points to the ``lammps`` Python package folder to be installed,
       * the ``-l`` flag points to the LAMMPS shared library file to be installed,
-      * the ``-v`` flag points to the ``version.h`` file in the LAMMPS source
+      * and the optional ``-n`` instructs the script to only build a wheel file
-      * and the optional ``-d`` flag to a custom (legacy) installation folder
+        but not attempt to install it.
-
-      If you use a legacy installation folder, you will need to set your
-      ``PYTHONPATH`` and ``LD_LIBRARY_PATH`` (and/or ``DYLD_LIBRARY_PATH``) environment
-      variables accordingly as explained in the description for "In place use".
 
    .. tab:: Virtual environment
 
@@ -257,32 +266,29 @@ this.
       package and the shared library file are installed into the
       following locations:
 
-      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+      +------------------------+--------------------------------------------------------+-------------------------------------------------------------+
       | File                   | Location                                               | Notes                                                       |
-      +========================+=================================================================+=============================================================+
+      +========================+========================================================+=============================================================+
-      | LAMMPS Python Module   | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps`` (32bit)   | ``X.Y`` depends on the installed Python version             |
+      | LAMMPS Python Module   | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps``  | ``X.Y`` depends on the installed Python version             |
-      |                        | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/lammps`` (64bit) |                                                             |
+      +------------------------+--------------------------------------------------------+-------------------------------------------------------------+
-      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+      | LAMMPS shared library  | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps``  | ``X.Y`` depends on the installed Python version             |
-      | LAMMPS shared library  | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps`` (32bit)   | ``X.Y`` depends on the installed Python version             |
+      +------------------------+--------------------------------------------------------+-------------------------------------------------------------+
-      |                        | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/lammps`` (64bit) |                                                             |
-      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
 
       If you do a full installation (CMake only) with "install", this
       leads to the following installation locations:
 
-      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+      +------------------------+--------------------------------------------------------+-------------------------------------------------------------+
       | File                   | Location                                               | Notes                                                       |
-      +========================+=================================================================+=============================================================+
+      +========================+========================================================+=============================================================+
-      | LAMMPS Python Module   | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps`` (32bit)   | ``X.Y`` depends on the installed Python version             |
+      | LAMMPS Python Module   | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps``  | ``X.Y`` depends on the installed Python version             |
-      |                        | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/lammps`` (64bit) |                                                             |
+      +------------------------+--------------------------------------------------------+-------------------------------------------------------------+
-      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
       | LAMMPS shared library  | * ``$VIRTUAL_ENV/lib/`` (32bit)                        | Set shared loader environment variable to this path         |
       |                        | * ``$VIRTUAL_ENV/lib64/`` (64bit)                      | (see below for more info on this)                           |
-      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+      +------------------------+--------------------------------------------------------+-------------------------------------------------------------+
       | LAMMPS executable      | * ``$VIRTUAL_ENV/bin/``                                |                                                             |
-      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+      +------------------------+--------------------------------------------------------+-------------------------------------------------------------+
       | LAMMPS potential files | * ``$VIRTUAL_ENV/share/lammps/potentials/``            | Set ``LAMMPS_POTENTIALS`` environment variable to this path |
-      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+      +------------------------+--------------------------------------------------------+-------------------------------------------------------------+
 
       In that case you need to modify the ``$HOME/myenv/bin/activate``
       script in a similar fashion you need to update your

doc/src/Run_options.rst

@@ -226,15 +226,6 @@ other executable(s) perform an MPI_Comm_split() with their own colors
 to shrink the MPI_COMM_WORLD communication to be the subset of
 processors they are actually running on.
 
-Currently, this is only used in LAMMPS to perform client/server
-messaging with another application.  LAMMPS can act as either a client
-or server (or both).  More details are given on the :doc:`Howto client/server <Howto_client_server>` doc page.
-
-Specifically, this refers to the "mpi/one" mode of messaging provided
-by the :doc:`message <message>` command and the CSlib library LAMMPS
-links with from the lib/message directory.  See the
-:doc:`message <message>` command for more details.
-
 ----------
 
 .. _cite:

doc/src/Run_output.rst

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

doc/src/Speed_kokkos.rst

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

doc/src/Tools.rst

@@ -87,7 +87,7 @@ Miscellaneous tools
 .. table_from_list::
    :columns: 6
 
-   * :ref:`CMake <cmake>`
+   * :ref:`LAMMPS coding standards <coding_standard>`
    * :ref:`emacs <emacs>`
    * :ref:`i-pi <ipi>`
    * :ref:`kate <kate>`
@@ -189,27 +189,32 @@ for the :doc:`chain benchmark <Speed_bench>`.
 
 ----------
 
-.. _cmake:
+.. _coding_standard:
 
-CMake tools
+LAMMPS coding standard
------------
+----------------------
 
-The ``cmbuild`` script is a wrapper around using ``cmake --build <dir>
+The ``coding_standard`` folder contains multiple python scripts to
---target`` and allows compiling LAMMPS in a :ref:`CMake build folder
+check for and apply some LAMMPS coding conventions.  The following
-<cmake_build>` with a make-like syntax regardless of the actual build
+scripts are available:
-tool and the specific name of the program used (e.g. ``ninja-v1.10`` or
-``gmake``) when using ``-D CMAKE_MAKE_PROGRAM=<name>``.
 
 .. parsed-literal::
 
-  Usage: cmbuild [-v] [-h] [-C <dir>] [-j <num>] [<target>]
+   permissions.py   # detects if sources have executable permissions and scripts have not
+   whitespace.py    # detects TAB characters and trailing whitespace
+   homepage.py      # detects outdated LAMMPS homepage URLs (pointing to sandia.gov instead of lammps.org)
+   errordocs.py     # detects deprecated error docs in header files
 
-  Options:
+The tools need to be given the main folder of the LAMMPS distribution
-    -h                print this message
+or individual file names as argument and will by default check them
-    -j <NUM>          allow processing of NUM concurrent tasks
+and report any non-compliance.  With the optional ``-f`` argument the
-    -C DIRECTORY      execute build in folder DIRECTORY
+corresponding script will try to change the non-compliant file(s) to
-    -v                produce verbose output
+match the conventions.
 
+For convenience this scripts can also be invoked by the make file in
+the ``src`` folder with, `make check-whitespace` or `make fix-whitespace`
+to either detect or edit the files.  Correspondingly for the other python
+scripts. `make check` will run all checks.
 
 ----------
 
@@ -277,17 +282,34 @@ at ens-lyon.fr, alain.dequidt at uca.fr
 eam database tool
 -----------------------------
 
-The tools/eam_database directory contains a Fortran program that will
+The tools/eam_database directory contains a Fortran and a Python program
-generate EAM alloy setfl potential files for any combination of 16
+that will generate EAM alloy setfl potential files for any combination
-elements: Cu, Ag, Au, Ni, Pd, Pt, Al, Pb, Fe, Mo, Ta, W, Mg, Co, Ti,
+of the 17 elements: Cu, Ag, Au, Ni, Pd, Pt, Al, Pb, Fe, Mo, Ta, W, Mg,
-Zr.  The files can then be used with the :doc:`pair_style eam/alloy <pair_eam>` command.
+Co, Ti, Zr, Cr.  The files can then be used with the :doc:`pair_style
+eam/alloy <pair_eam>` command.
 
-The tool is authored by Xiaowang Zhou (Sandia), xzhou at sandia.gov,
+The Fortran version of the tool was authored by Xiaowang Zhou (Sandia),
-and is based on his paper:
+xzhou at sandia.gov, with updates from Lucas Hale (NIST) lucas.hale at
+nist.gov and is based on his paper:
 
 X. W. Zhou, R. A. Johnson, and H. N. G. Wadley, Phys. Rev. B, 69,
 144113 (2004).
 
+The parameters for Cr were taken from:
+
+Lin Z B, Johnson R A and Zhigilei L V, Phys. Rev. B 77 214108 (2008).
+
+The Python version of the tool was authored  by Germain Clavier
+(TU Eindhoven) g.m.g.c.clavier at tue.nl or germain.clavier at gmail.com
+
+.. note::
+
+   The parameters in the database are only optimized for individual
+   elements. The mixed parameters for interactions between different
+   elements generated by this tool are derived from simple mixing rules
+   and are thus inferior to parameterizations that are specifically
+   optimized for specific mixtures and combinations of elements.
+
 ----------
 
 .. _eamgn: