Merge pull request #2648 from akohlmey/next_lammps_version

Update version strings for the next patch release

.github/CONTRIBUTING.md

@@ -108,7 +108,7 @@ For bug reports, the next step is that one of the core LAMMPS developers will se
 
 For submitting pull requests, there is a [detailed tutorial](https://lammps.sandia.gov/doc/Howto_github.html) in the LAMMPS manual. Thus only a brief breakdown of the steps is presented here. Please note, that the LAMMPS developers are still reviewing and trying to improve the process. If you are unsure about something, do not hesitate to post a question on the lammps-users mailing list or contact one fo the core LAMMPS developers.
 Immediately after the submission, the LAMMPS continuing integration server at ci.lammps.org will download your submitted branch and perform a simple compilation test, i.e. will test whether your submitted code can be compiled under various conditions. It will also do a check on whether your included documentation translates cleanly. Whether these tests are successful or fail will be recorded. If a test fails, please inspect the corresponding output on the CI server and take the necessary steps, if needed, so that the code can compile cleanly again. The test will be re-run each the pull request is updated with a push to the remote branch on GitHub.
-Next a LAMMPS core developer will self-assign and do an overall technical assessment of the submission. If you are not yet registered as a LAMMPS collaborator, you will receive an invitation for that. As part of the assesment, the pull request will be categorized with labels. There are two special labels: `needs_work` (indicates that work from the submitter of the pull request is needed) and `work_in_progress` (indicates, that the assigned LAMMPS developer will make changes, if not done by the contributor who made the submit). 
+Next a LAMMPS core developer will self-assign and do an overall technical assessment of the submission. If you are not yet registered as a LAMMPS collaborator, you will receive an invitation for that. As part of the assessment, the pull request will be categorized with labels. There are two special labels: `needs_work` (indicates that work from the submitter of the pull request is needed) and `work_in_progress` (indicates, that the assigned LAMMPS developer will make changes, if not done by the contributor who made the submit). 
 You may also receive comments and suggestions on the overall submission or specific details and on occasion specific requests for changes as part of the review. If permitted, also additional changes may be pushed into your pull request branch or a pull request may be filed in your LAMMPS fork on GitHub to include those changes.
 The LAMMPS developer may then decide to assign the pull request to another developer (e.g. when that developer is more knowledgeable about the submitted feature or enhancement or has written the modified code). It may also happen, that additional developers are requested to provide a review and approve the changes. For submissions, that may change the general behavior of LAMMPS, or where a possibility of unwanted side effects exists, additional tests may be requested by the assigned developer.
 If the assigned developer is satisfied and considers the submission ready for inclusion into LAMMPS, the pull request will receive approvals and be merged into the master branch by one of the core LAMMPS developers. After the pull request is merged, you may delete the feature branch used for the pull request in your personal LAMMPS fork.

.github/workflows/codeql-analysis.yml

@@ -0,0 +1,47 @@
+# GitHub action to run static code analysis on C++ and Python code
+name: "CodeQL Code Analysis"
+
+on:
+  push:
+    branches: [master]
+
+jobs:
+  analyze:
+    name: Analyze
+    if: ${{ github.repository == 'lammps/lammps' }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: ['cpp', 'python']
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+      with:
+        fetch-depth: 2
+
+    - name: Setup Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.x'
+
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v1
+      with:
+        languages: ${{ matrix.language }}
+
+    - name: Create Build Environment
+      run: cmake -E make_directory ${{github.workspace}}/build
+
+    - name: Building LAMMPS via CMake
+      if: ${{ matrix.language == 'cpp' }}
+      shell: bash
+      working-directory: ${{github.workspace}}/build
+      run: |
+        cmake -C $GITHUB_WORKSPACE/cmake/presets/most.cmake $GITHUB_WORKSPACE/cmake
+        cmake --build . --parallel 2
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v1

.github/workflows/unittest-macos.yml

@@ -0,0 +1,34 @@
+# GitHub action to build LAMMPS on MacOS and run unit tests
+name: "Unittest for MacOS"
+
+on:
+  push:
+    branches: [master]
+
+jobs:
+  build:
+    name: MacOS Unit Test
+    if: ${{ github.repository == 'lammps/lammps' }}
+    runs-on: macos-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+      with:
+        fetch-depth: 2
+
+    - name: Create Build Environment
+      run: cmake -E make_directory ${{github.workspace}}/build
+
+    - name: Building LAMMPS via CMake
+      shell: bash
+      working-directory: ${{github.workspace}}/build
+      run: |
+        cmake -C $GITHUB_WORKSPACE/cmake/presets/most.cmake $GITHUB_WORKSPACE/cmake \
+              -DENABLE_TESTING=ON -DBUILD_SHARED_LIBS=ON -DLAMMPS_EXCEPTIONS=ON
+        cmake --build . --parallel 2
+
+    - name: Run Tests
+      working-directory: ${{github.workspace}}/build
+      shell: bash
+      run: ctest -V

LICENSE

@@ -1,6 +1,6 @@
 GNU GENERAL PUBLIC LICENSE
 
-Version 2, June 1991 
+Version 2, June 1991
 
 Copyright (C) 1989, 1991 Free Software Foundation, Inc.  
 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
@@ -301,9 +301,8 @@ one line to give the program's name and an idea of what it does.
 Copyright (C) yyyy  name of author
 
 This program is free software; you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation; either version 2 of the License, or (at
-your option) any later version.
+it under the terms of the GNU General Public License version 2 as
+published by the Free Software Foundation.
 
 This program is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the implied warranty of

README

@@ -37,14 +37,14 @@ tools                      pre- and post-processing tools
 
 Point your browser at any of these files to get started:
 
-https://lammps.sandia.gov/doc/Manual.html         LAMMPS user manual
+https://lammps.sandia.gov/doc/Manual.html         LAMMPS manual
 https://lammps.sandia.gov/doc/Intro.html          hi-level introduction
 https://lammps.sandia.gov/doc/Build.html          how to build LAMMPS
 https://lammps.sandia.gov/doc/Run_head.html       how to run LAMMPS
 https://lammps.sandia.gov/doc/Commands_all.html   Table of available commands
-https://lammps.sandia.gov/doc/pg_library.html     LAMMPS programmer guide
+https://lammps.sandia.gov/doc/Library.html        LAMMPS library interfaces
 https://lammps.sandia.gov/doc/Modify.html         how to modify and extend LAMMPS
-https://lammps.sandia.gov/doc/pg_developer.html   LAMMPS developer guide
+https://lammps.sandia.gov/doc/Developer.html      LAMMPS developer info
 
 You can also create these doc pages locally:
 

cmake/CMakeLists.txt

@@ -25,15 +25,22 @@ set(LAMMPS_POTENTIALS_DIR ${LAMMPS_DIR}/potentials)
 find_package(Git)
 
 # by default, install into $HOME/.local (not /usr/local), so that no root access (and sudo!!) is needed
-if (CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
-  set(CMAKE_INSTALL_PREFIX "$ENV{HOME}/.local" CACHE PATH "default install path" FORCE )
+if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
+  set(CMAKE_INSTALL_PREFIX "$ENV{HOME}/.local" CACHE PATH "Default install path" FORCE)
+endif()
+
+# If enabled, no need to use LD_LIBRARY_PATH / DYLD_LIBRARY_PATH when installed
+option(LAMMPS_INSTALL_RPATH "Set runtime path for shared libraries linked to LAMMPS binaries" OFF)
+if (LAMMPS_INSTALL_RPATH)
+  set(CMAKE_INSTALL_RPATH ${CMAKE_INSTALL_FULL_LIBDIR})
+  set(CMAKE_INSTALL_RPATH_USE_LINK_PATH ON)
 endif()
 
 # Cmake modules/macros are in a subdirectory to keep this file cleaner
 set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/Modules)
 
 # make sure LIBRARY_PATH is set if environment variable is set
-if (DEFINED ENV{LIBRARY_PATH})
+if(DEFINED ENV{LIBRARY_PATH})
   list(APPEND CMAKE_LIBRARY_PATH "$ENV{LIBRARY_PATH}")
   message(STATUS "Appending $ENV{LIBRARY_PATH} to CMAKE_LIBRARY_PATH: ${CMAKE_LIBRARY_PATH}")
 endif()
@@ -107,13 +114,15 @@ option(CMAKE_VERBOSE_MAKEFILE "Generate verbose Makefiles" OFF)
 set(STANDARD_PACKAGES ASPHERE BODY CLASS2 COLLOID COMPRESS DIPOLE
   GRANULAR KSPACE LATTE MANYBODY MC MESSAGE MISC MLIAP MOLECULE PERI POEMS
   QEQ REPLICA RIGID SHOCK SPIN SNAP SRD KIM PYTHON MSCG MPIIO VORONOI
-  USER-ATC USER-AWPMD USER-BOCS USER-CGDNA USER-MESODPD USER-CGSDK USER-COLVARS
-  USER-DIFFRACTION USER-DPD USER-DRUDE USER-EFF USER-FEP USER-H5MD USER-LB
-  USER-MANIFOLD USER-MEAMC USER-MESONT USER-MGPT USER-MISC USER-MOFFF USER-MOLFILE
-  USER-NETCDF USER-PHONON USER-PLUMED USER-PTM USER-QTB USER-REACTION
-  USER-REAXC USER-SCAFACOS USER-SDPD USER-SMD USER-SMTBQ USER-SPH USER-TALLY
-  USER-UEF USER-VTK USER-QUIP USER-QMMM USER-YAFF USER-ADIOS)
-set(SUFFIX_PACKAGES CORESHELL USER-OMP KOKKOS OPT USER-INTEL GPU)
+  USER-ADIOS USER-ATC USER-AWPMD USER-BOCS USER-CGDNA USER-MESODPD USER-CGSDK
+  USER-COLVARS USER-DIFFRACTION USER-DPD USER-DRUDE USER-EFF USER-FEP USER-H5MD
+  USER-LB USER-MANIFOLD USER-MEAMC USER-MESONT USER-MGPT USER-MISC USER-MOFFF
+  USER-MOLFILE USER-NETCDF USER-PHONON USER-PLUMED USER-PTM USER-QTB
+  USER-REACTION USER-REAXC USER-SCAFACOS USER-SDPD USER-SMD USER-SMTBQ USER-SPH
+  USER-TALLY USER-UEF USER-VTK USER-QUIP USER-QMMM USER-YAFF)
+
+set(SUFFIX_PACKAGES CORESHELL GPU KOKKOS OPT USER-INTEL USER-OMP)
+
 foreach(PKG ${STANDARD_PACKAGES} ${SUFFIX_PACKAGES})
   option(PKG_${PKG} "Build ${PKG} Package" OFF)
 endforeach()
@@ -154,8 +163,7 @@ if(BUILD_MPI)
     endif()
   endif()
 else()
-  enable_language(C)
-  file(GLOB MPI_SOURCES ${LAMMPS_SOURCE_DIR}/STUBS/mpi.c)
+  file(GLOB MPI_SOURCES ${LAMMPS_SOURCE_DIR}/STUBS/mpi.cpp)
   add_library(mpi_stubs STATIC ${MPI_SOURCES})
   set_target_properties(mpi_stubs PROPERTIES OUTPUT_NAME lammps_mpi_stubs${LAMMPS_MACHINE})
   target_include_directories(mpi_stubs PUBLIC $<BUILD_INTERFACE:${LAMMPS_SOURCE_DIR}/STUBS>)
@@ -220,6 +228,7 @@ if(BUILD_OMP)
   endif()
 
   if (((CMAKE_CXX_COMPILER_ID STREQUAL "GNU") AND (CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 9.0)) OR
+      (CMAKE_CXX_COMPILER_ID STREQUAL "PGI") OR
       ((CMAKE_CXX_COMPILER_ID STREQUAL "Clang") AND (CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 10.0)) OR
       ((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.
@@ -372,7 +381,7 @@ else()
   set(CUDA_REQUEST_PIC)
 endif()
 
-foreach(PKG_WITH_INCL KSPACE PYTHON VORONOI USER-COLVARS USER-MOLFILE USER-NETCDF USER-PLUMED USER-QMMM
+foreach(PKG_WITH_INCL KSPACE PYTHON MLIAP VORONOI USER-COLVARS USER-MOLFILE USER-NETCDF USER-PLUMED USER-QMMM
         USER-QUIP USER-SCAFACOS USER-SMD USER-VTK KIM LATTE MESSAGE MSCG COMPRESS)
   if(PKG_${PKG_WITH_INCL})
     include(Packages/${PKG_WITH_INCL})
@@ -579,7 +588,7 @@ add_dependencies(lammps gitversion)
 ############################################
 get_property(LANGUAGES GLOBAL PROPERTY ENABLED_LANGUAGES)
 list (FIND LANGUAGES "Fortran" _index)
-if (${_index} GREATER -1)
+if(${_index} GREATER -1)
   target_link_libraries(lammps PRIVATE ${CMAKE_Fortran_IMPLICIT_LINK_LIBRARIES})
 endif()
 set(LAMMPS_CXX_HEADERS angle.h atom.h bond.h citeme.h comm.h compute.h dihedral.h domain.h error.h fix.h force.h group.h improper.h
@@ -649,7 +658,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.8 3.7 3.6 3.5)
+    set(Python_ADDITIONAL_VERSIONS 3.9 3.8 3.7 3.6 3.5)
     find_package(PythonInterp) # Deprecated since version 3.12
     if(PYTHONINTERP_FOUND)
         set(Python_EXECUTABLE ${PYTHON_EXECUTABLE})
@@ -659,10 +668,10 @@ if(BUILD_SHARED_LIBS)
   endif()
   if (Python_EXECUTABLE)
     add_custom_target(
-      install-python
-      ${Python_EXECUTABLE} install.py -v ${LAMMPS_SOURCE_DIR}/version.h
-      -m ${LAMMPS_PYTHON_DIR}/lammps.py
-      -l ${CMAKE_BINARY_DIR}/liblammps${CMAKE_SHARED_LIBRARY_SUFFIX}
+      install-python ${CMAKE_COMMAND} -E remove_directory build
+      COMMAND ${Python_EXECUTABLE} install.py -v ${LAMMPS_SOURCE_DIR}/version.h
+      -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()
@@ -691,11 +700,8 @@ if(BUILD_SHARED_LIBS OR PKG_PYTHON)
     find_package(Python COMPONENTS Interpreter)
   endif()
   if (Python_EXECUTABLE)
-    execute_process(COMMAND ${Python_EXECUTABLE}
-      -c "import distutils.sysconfig as cg; print(cg.get_python_lib(1,0,prefix='${CMAKE_INSTALL_PREFIX}'))"
-      OUTPUT_VARIABLE PYTHON_DEFAULT_INSTDIR OUTPUT_STRIP_TRAILING_WHITESPACE)
-    set(PYTHON_INSTDIR ${PYTHON_DEFAULT_INSTDIR} CACHE PATH "Installation folder for LAMMPS Python module")
-    install(FILES ${LAMMPS_PYTHON_DIR}/lammps.py DESTINATION ${PYTHON_INSTDIR})
+    file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/python)
+    install(CODE "execute_process(COMMAND ${Python_EXECUTABLE} setup.py build -b ${CMAKE_BINARY_DIR}/python install --prefix=${CMAKE_INSTALL_PREFIX} --root=\$ENV{DESTDIR}/ WORKING_DIRECTORY ${LAMMPS_PYTHON_DIR})")
   endif()
 endif()
 
@@ -739,14 +745,14 @@ if(OPTIONS)
 endif()
 get_property(LANGUAGES GLOBAL PROPERTY ENABLED_LANGUAGES)
 list (FIND LANGUAGES "Fortran" _index)
-if (${_index} GREATER -1)
+if(${_index} GREATER -1)
   message(STATUS "Fortran Compiler: ${CMAKE_Fortran_COMPILER}
       Type:          ${CMAKE_Fortran_COMPILER_ID}
       Version:       ${CMAKE_Fortran_COMPILER_VERSION}
       Fortran Flags:${CMAKE_Fortran_FLAGS} ${CMAKE_Fortran_FLAGS_${BTYPE}}")
 endif()
 list (FIND LANGUAGES "C" _index)
-if (${_index} GREATER -1)
+if(${_index} GREATER -1)
   message(STATUS "C compiler:       ${CMAKE_C_COMPILER}
       Type:          ${CMAKE_C_COMPILER_ID}
       Version:       ${CMAKE_C_COMPILER_VERSION}
@@ -778,9 +784,7 @@ if(PKG_GPU)
   message(STATUS "<<< GPU package settings >>>
 -- GPU API:          ${GPU_API}")
   if(GPU_API STREQUAL "CUDA")
-    message(STATUS "GPU architecture: ${GPU_ARCH}")
-  elseif(GPU_API STREQUAL "OPENCL")
-    message(STATUS "OpenCL tuning:    ${OCL_TUNE}")
+    message(STATUS "GPU default architecture: ${GPU_ARCH}")
   elseif(GPU_API STREQUAL "HIP")
     message(STATUS "HIP platform:     ${HIP_PLATFORM}")
     message(STATUS "HIP architecture: ${HIP_ARCH}")

cmake/Modules/CodingStandard.cmake

@@ -8,7 +8,7 @@ else()
     find_package(Python3 COMPONENTS Interpreter QUIET)
 endif()
 
-if (Python3_EXECUTABLE)
+if(Python3_EXECUTABLE)
     if(Python3_VERSION VERSION_GREATER_EQUAL 3.5)
         add_custom_target(
           check-whitespace

cmake/Modules/Documentation.cmake

@@ -50,9 +50,9 @@ if(BUILD_DOC)
     OUTPUT ${DOC_BUILD_DIR}/requirements.txt
     DEPENDS docenv ${DOCENV_REQUIREMENTS_FILE}
     COMMAND ${CMAKE_COMMAND} -E copy ${DOCENV_REQUIREMENTS_FILE} ${DOC_BUILD_DIR}/requirements.txt
-    COMMAND ${DOCENV_BINARY_DIR}/pip install --upgrade pip
-    COMMAND ${DOCENV_BINARY_DIR}/pip install --upgrade ${LAMMPS_DOC_DIR}/utils/converters
-    COMMAND ${DOCENV_BINARY_DIR}/pip install --use-feature=2020-resolver -r ${DOC_BUILD_DIR}/requirements.txt --upgrade
+    COMMAND ${DOCENV_BINARY_DIR}/pip $ENV{PIP_OPTIONS} install --upgrade pip
+    COMMAND ${DOCENV_BINARY_DIR}/pip $ENV{PIP_OPTIONS} install --upgrade ${LAMMPS_DOC_DIR}/utils/converters
+    COMMAND ${DOCENV_BINARY_DIR}/pip $ENV{PIP_OPTIONS} install -r ${DOC_BUILD_DIR}/requirements.txt --upgrade
   )
 
   # download mathjax distribution and unpack to folder "mathjax"

cmake/Modules/FindCythonize.cmake

@@ -0,0 +1,30 @@
+# Find the Cythonize tool.
+#
+# This code sets the following variables:
+#
+#  Cythonize_EXECUTABLE
+#
+# adapted from https://github.com/cmarshall108/cython-cmake-example/blob/master/cmake/FindCython.cmake
+#=============================================================================
+
+if(CMAKE_VERSION VERSION_LESS 3.12)
+    find_package(PythonInterp 3.6 QUIET) # Deprecated since version 3.12
+    if(PYTHONINTERP_FOUND)
+        set(Python3_EXECUTABLE ${PYTHON_EXECUTABLE})
+    endif()
+else()
+    find_package(Python3 3.6 COMPONENTS Interpreter QUIET)
+endif()
+
+# Use the Cython executable that lives next to the Python executable
+# if it is a local installation.
+if(Python3_EXECUTABLE)
+  get_filename_component(_python_path ${Python3_EXECUTABLE} PATH)
+  find_program(Cythonize_EXECUTABLE
+    NAMES cythonize3 cythonize cythonize.bat
+    HINTS ${_python_path})
+endif()
+
+include(FindPackageHandleStandardArgs)
+FIND_PACKAGE_HANDLE_STANDARD_ARGS(Cythonize REQUIRED_VARS Cythonize_EXECUTABLE)
+mark_as_advanced(Cythonize_EXECUTABLE)

cmake/Modules/GTest.cmake

@@ -20,10 +20,10 @@ ExternalProject_Add(googletest
                                     -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
                                     -DCMAKE_MAKE_PROGRAM=${CMAKE_MAKE_PROGRAM}
                                     -DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}
-                    BUILD_BYPRODUCTS <BINARY_DIR>/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gtest${GTEST_LIB_POSTFIX}.a
-                                     <BINARY_DIR>/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gmock${GTEST_LIB_POSTFIX}.a
-                                     <BINARY_DIR>/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gtest_main${GTEST_LIB_POSTFIX}.a
-                                     <BINARY_DIR>/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gmock_main${GTEST_LIB_POSTFIX}.a
+                    BUILD_BYPRODUCTS <BINARY_DIR>/lib/libgtest${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
+                                     <BINARY_DIR>/lib/libgmock${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
+                                     <BINARY_DIR>/lib/libgtest_main${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
+                                     <BINARY_DIR>/lib/libgmock_main${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX}
                     LOG_DOWNLOAD ON
                     LOG_CONFIGURE ON
                     LOG_BUILD ON
@@ -39,10 +39,10 @@ file(MAKE_DIRECTORY ${GTEST_INCLUDE_DIR})
 file(MAKE_DIRECTORY ${GMOCK_INCLUDE_DIR})
 
 ExternalProject_Get_Property(googletest BINARY_DIR)
-set(GTEST_LIBRARY_PATH ${BINARY_DIR}/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gtest${GTEST_LIB_POSTFIX}.a)
-set(GMOCK_LIBRARY_PATH ${BINARY_DIR}/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gmock${GTEST_LIB_POSTFIX}.a)
-set(GTEST_MAIN_LIBRARY_PATH ${BINARY_DIR}/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gtest_main${GTEST_LIB_POSTFIX}.a)
-set(GMOCK_MAIN_LIBRARY_PATH ${BINARY_DIR}/lib/${CMAKE_FIND_LIBRARY_PREFIXES}gmock_main${GTEST_LIB_POSTFIX}.a)
+set(GTEST_LIBRARY_PATH ${BINARY_DIR}/lib/libgtest${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX})
+set(GMOCK_LIBRARY_PATH ${BINARY_DIR}/lib/libgmock${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX})
+set(GTEST_MAIN_LIBRARY_PATH ${BINARY_DIR}/lib/libgtest_main${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX})
+set(GMOCK_MAIN_LIBRARY_PATH ${BINARY_DIR}/lib/libgmock_main${GTEST_LIB_POSTFIX}${CMAKE_STATIC_LIBRARY_SUFFIX})
 
 # Prevent GoogleTest from overriding our compiler/linker options
 # when building with Visual Studio

cmake/Modules/LAMMPSUtils.cmake

@@ -50,6 +50,7 @@ function(check_for_autogen_files source_dir)
     file(GLOB SRC_AUTOGEN_FILES ${source_dir}/style_*.h)
     file(GLOB SRC_AUTOGEN_PACKAGES ${source_dir}/packages_*.h)
     list(APPEND SRC_AUTOGEN_FILES ${SRC_AUTOGEN_PACKAGES} ${source_dir}/lmpinstalledpkgs.h ${source_dir}/lmpgitversion.h)
+    list(APPEND SRC_AUTOGEN_FILES ${SRC_AUTOGEN_PACKAGES} ${source_dir}/mliap_model_python_couple.h ${source_dir}/mliap_model_python_couple.cpp)
     foreach(_SRC ${SRC_AUTOGEN_FILES})
       get_filename_component(FILENAME "${_SRC}" NAME)
       if(EXISTS ${source_dir}/${FILENAME})

cmake/Modules/MPI4WIN.cmake

@@ -1,7 +1,7 @@
 # Download and configure custom MPICH files for Windows
 message(STATUS "Downloading and configuring MPICH-1.4.1 for Windows")
 include(ExternalProject)
-if (CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64")
+if(CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64")
   ExternalProject_Add(mpi4win_build
     URL https://download.lammps.org/thirdparty/mpich2-win64-devel.tar.gz
     URL_MD5 4939fdb59d13182fd5dd65211e469f14

cmake/Modules/OpenCLLoader.cmake

@@ -0,0 +1,48 @@
+message(STATUS "Downloading and building OpenCL loader library")
+
+include(ExternalProject)
+set(OPENCL_LOADER_URL "https://download.lammps.org/thirdparty/opencl-loader-2020.12.18.tar.gz" CACHE STRING "URL for OpenCL loader tarball")
+mark_as_advanced(OPENCL_LOADER_URL)
+ExternalProject_Add(opencl_loader
+                    URL ${OPENCL_LOADER_URL}
+                    URL_MD5         011cdcbd41030be94f3fced6d763a52a
+                    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}")
+
+

cmake/Modules/Packages/GPU.cmake

@@ -1,7 +1,10 @@
 set(GPU_SOURCES_DIR ${LAMMPS_SOURCE_DIR}/GPU)
 set(GPU_SOURCES ${GPU_SOURCES_DIR}/gpu_extra.h
                 ${GPU_SOURCES_DIR}/fix_gpu.h
-                ${GPU_SOURCES_DIR}/fix_gpu.cpp)
+                ${GPU_SOURCES_DIR}/fix_gpu.cpp
+                ${GPU_SOURCES_DIR}/fix_nh_gpu.h
+                ${GPU_SOURCES_DIR}/fix_nh_gpu.cpp)
+target_compile_definitions(lammps PRIVATE -DLMP_GPU)
 
 set(GPU_API "opencl" CACHE STRING "API used by GPU package")
 set(GPU_API_VALUES opencl cuda hip)
@@ -35,6 +38,9 @@ if(GPU_API STREQUAL "CUDA")
   option(CUDPP_OPT "Enable CUDPP_OPT" ON)
   option(CUDA_MPS_SUPPORT "Enable tweaks to support CUDA Multi-process service (MPS)" OFF)
   if(CUDA_MPS_SUPPORT)
+    if(CUDPP_OPT)
+      message(FATAL_ERROR "Must use -DCUDPP_OPT=OFF with -DGPU_CUDA_MPS_SUPPORT=ON")
+    endif()
     set(GPU_CUDA_MPS_FLAGS "-DCUDA_PROXY")
   endif()
 
@@ -97,6 +103,10 @@ if(GPU_API STREQUAL "CUDA")
   if(CUDA_VERSION VERSION_GREATER_EQUAL "11.0")
     string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_80,code=[sm_80,compute_80]")
   endif()
+  # Ampere (GPU Arch 8.6) is supported by CUDA 11.1 and later
+  if(CUDA_VERSION VERSION_GREATER_EQUAL "11.1")
+    string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_86,code=[sm_86,compute_86]")
+  endif()
   if(CUDA_VERSION VERSION_GREATER_EQUAL "12.0")
     message(WARNING "Unsupported CUDA version. Use at your own risk.")
   endif()
@@ -135,27 +145,13 @@ if(GPU_API STREQUAL "CUDA")
   target_include_directories(nvc_get_devices PRIVATE ${CUDA_INCLUDE_DIRS})
 
 elseif(GPU_API STREQUAL "OPENCL")
-  if(${CMAKE_SYSTEM_NAME} STREQUAL "Windows")
-    # download and unpack support binaries for compilation of windows binaries.
-    set(LAMMPS_THIRDPARTY_URL "https://download.lammps.org/thirdparty")
-    file(DOWNLOAD "${LAMMPS_THIRDPARTY_URL}/opencl-win-devel.tar.gz" "${CMAKE_CURRENT_BINARY_DIR}/opencl-win-devel.tar.gz"
-            EXPECTED_MD5 2c00364888d5671195598b44c2e0d44d)
-    execute_process(COMMAND ${CMAKE_COMMAND} -E tar xzf opencl-win-devel.tar.gz WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
-    add_library(OpenCL::OpenCL UNKNOWN IMPORTED)
-    if(${CMAKE_SYSTEM_PROCESSOR} STREQUAL "x86")
-      set_target_properties(OpenCL::OpenCL PROPERTIES IMPORTED_LOCATION "${CMAKE_CURRENT_BINARY_DIR}/OpenCL/lib_win32/libOpenCL.dll")
-    elseif(${CMAKE_SYSTEM_PROCESSOR} STREQUAL "x86_64")
-      set_target_properties(OpenCL::OpenCL PROPERTIES IMPORTED_LOCATION "${CMAKE_CURRENT_BINARY_DIR}/OpenCL/lib_win64/libOpenCL.dll")
-    endif()
-    set_target_properties(OpenCL::OpenCL PROPERTIES INTERFACE_INCLUDE_DIRECTORIES "${CMAKE_CURRENT_BINARY_DIR}/OpenCL/include")
+  option(USE_STATIC_OPENCL_LOADER "Download and include a static OpenCL ICD loader" ON)
+  mark_as_advanced(USE_STATIC_OPENCL_LOADER)
+  if (USE_STATIC_OPENCL_LOADER)
+    include(OpenCLLoader)
   else()
     find_package(OpenCL REQUIRED)
   endif()
-  set(OCL_TUNE "generic" CACHE STRING "OpenCL Device Tuning")
-  set(OCL_TUNE_VALUES intel fermi kepler cypress generic)
-  set_property(CACHE OCL_TUNE PROPERTY STRINGS ${OCL_TUNE_VALUES})
-  validate_option(OCL_TUNE OCL_TUNE_VALUES)
-  string(TOUPPER ${OCL_TUNE} OCL_TUNE)
 
   include(OpenCLUtils)
   set(OCL_COMMON_HEADERS ${LAMMPS_LIB_SOURCE_DIR}/gpu/lal_preprocessor.h ${LAMMPS_LIB_SOURCE_DIR}/gpu/lal_aux_fun1.h)
@@ -199,7 +195,7 @@ elseif(GPU_API STREQUAL "OPENCL")
   add_library(gpu STATIC ${GPU_LIB_SOURCES})
   target_link_libraries(gpu PRIVATE OpenCL::OpenCL)
   target_include_directories(gpu PRIVATE ${CMAKE_CURRENT_BINARY_DIR}/gpu)
-  target_compile_definitions(gpu PRIVATE -D_${GPU_PREC_SETTING} -D${OCL_TUNE}_OCL -DMPI_GERYON -DUCL_NO_EXIT)
+  target_compile_definitions(gpu PRIVATE -D_${GPU_PREC_SETTING} -DMPI_GERYON -DGERYON_NUMA_FISSION -DUCL_NO_EXIT)
   target_compile_definitions(gpu PRIVATE -DUSE_OPENCL)
 
   target_link_libraries(lammps PRIVATE gpu)
@@ -207,6 +203,7 @@ elseif(GPU_API STREQUAL "OPENCL")
   add_executable(ocl_get_devices ${LAMMPS_LIB_SOURCE_DIR}/gpu/geryon/ucl_get_devices.cpp)
   target_compile_definitions(ocl_get_devices PRIVATE -DUCL_OPENCL)
   target_link_libraries(ocl_get_devices PRIVATE OpenCL::OpenCL)
+  add_dependencies(ocl_get_devices OpenCL::OpenCL)
 elseif(GPU_API STREQUAL "HIP")
   if(NOT DEFINED HIP_PATH)
       if(NOT DEFINED ENV{HIP_PATH})
@@ -389,13 +386,10 @@ elseif(GPU_API STREQUAL "HIP")
   target_link_libraries(lammps PRIVATE gpu)
 endif()
 
-# GPU package
-FindStyleHeaders(${GPU_SOURCES_DIR} FIX_CLASS fix_ FIX)
-
 set_property(GLOBAL PROPERTY "GPU_SOURCES" "${GPU_SOURCES}")
-
-# detects styles which have GPU version
+# detect styles which have a GPU version
 RegisterStylesExt(${GPU_SOURCES_DIR} gpu GPU_SOURCES)
+RegisterFixStyle(${GPU_SOURCES_DIR}/fix_gpu.h)
 
 get_property(GPU_SOURCES GLOBAL PROPERTY GPU_SOURCES)
 

cmake/Modules/Packages/KIM.cmake

@@ -19,6 +19,8 @@ if(CURL_FOUND)
     target_compile_definitions(lammps PRIVATE -DLMP_NO_SSL_CHECK)
   endif()
 endif()
+set(KIM_EXTRA_UNITTESTS OFF CACHE STRING "Set extra unit tests verbose mode on/off. If on, extra tests are included.")
+mark_as_advanced(KIM_EXTRA_UNITTESTS)
 find_package(PkgConfig QUIET)
 set(DOWNLOAD_KIM_DEFAULT ON)
 if(PKG_CONFIG_FOUND)
@@ -34,8 +36,8 @@ if(DOWNLOAD_KIM)
   enable_language(C)
   enable_language(Fortran)
   ExternalProject_Add(kim_build
-    URL https://s3.openkim.org/kim-api/kim-api-2.1.3.txz
-    URL_MD5 6ee829a1bbba5f8b9874c88c4c4ebff8
+    URL https://s3.openkim.org/kim-api/kim-api-2.2.1.txz
+    URL_MD5 ae1ddda2ef7017ea07934e519d023dca
     BINARY_DIR build
     CMAKE_ARGS ${CMAKE_REQUEST_PIC}
                -DCMAKE_C_COMPILER=${CMAKE_C_COMPILER}
@@ -53,11 +55,28 @@ if(DOWNLOAD_KIM)
   add_library(LAMMPS::KIM UNKNOWN IMPORTED)
   set_target_properties(LAMMPS::KIM PROPERTIES
     IMPORTED_LOCATION "${INSTALL_DIR}/lib/libkim-api${CMAKE_SHARED_LIBRARY_SUFFIX}"
-    INTERFACE_INCLUDE_DIRECTORIES "${INSTALL_DIR}/include/kim-api")
-  target_link_libraries(lammps PRIVATE LAMMPS::KIM)
+    INTERFACE_INCLUDE_DIRECTORIES "${INSTALL_DIR}/include/kim-api"
+    )
   add_dependencies(LAMMPS::KIM kim_build)
+  target_link_libraries(lammps PRIVATE LAMMPS::KIM)
+  # Set rpath so lammps build directory is relocatable
+  if("${CMAKE_SYSTEM_NAME}" STREQUAL "Darwin")
+    set(_rpath_prefix "@loader_path")
+  else()
+    set(_rpath_prefix "$ORIGIN")
+  endif()
+  set_target_properties(lmp PROPERTIES
+    BUILD_RPATH "${_rpath_prefix}/kim_build-prefix/lib"
+    )
 else()
-  find_package(PkgConfig REQUIRED)
-  pkg_check_modules(KIM-API REQUIRED IMPORTED_TARGET libkim-api>=${KIM-API_MIN_VERSION})
-  target_link_libraries(lammps PRIVATE PkgConfig::KIM-API)
+  if(KIM-API_FOUND AND KIM-API_VERSION VERSION_GREATER_EQUAL 2.2.0)
+    # For kim-api >= 2.2.0
+    find_package(KIM-API 2.2.0 CONFIG REQUIRED)
+    target_link_libraries(lammps PRIVATE KIM-API::kim-api)
+  else()
+    # For kim-api 2.1.3 (consistent with previous version of this file)
+    find_package(PkgConfig REQUIRED)
+    pkg_check_modules(KIM-API REQUIRED IMPORTED_TARGET libkim-api>=${KIM-API_MIN_VERSION})
+    target_link_libraries(lammps PRIVATE PkgConfig::KIM-API)
+  endif()
 endif()

cmake/Modules/Packages/KOKKOS.cmake

@@ -1,4 +1,7 @@
 ########################################################################
+# As of version 3.3.0 Kokkos requires C++14
+set(CMAKE_CXX_STANDARD 14)
+########################################################################
 # consistency checks and Kokkos options/settings required by LAMMPS
 if(Kokkos_ENABLE_CUDA)
   message(STATUS "KOKKOS: Enabling CUDA LAMBDA function support")
@@ -35,8 +38,8 @@ if(DOWNLOAD_KOKKOS)
   list(APPEND KOKKOS_LIB_BUILD_ARGS "-DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}")
   include(ExternalProject)
   ExternalProject_Add(kokkos_build
-    URL https://github.com/kokkos/kokkos/archive/3.2.00.tar.gz
-    URL_MD5 81569170fe232e5e64ab074f7cca5e50
+    URL https://github.com/kokkos/kokkos/archive/3.3.01.tar.gz
+    URL_MD5 08201d1c7cf5bc458ce0f5b44a629d5a
     CMAKE_ARGS ${KOKKOS_LIB_BUILD_ARGS}
     BUILD_BYPRODUCTS <INSTALL_DIR>/lib/libkokkoscore.a
   )
@@ -50,7 +53,7 @@ if(DOWNLOAD_KOKKOS)
   target_link_libraries(lammps PRIVATE LAMMPS::KOKKOS)
   add_dependencies(LAMMPS::KOKKOS kokkos_build)
 elseif(EXTERNAL_KOKKOS)
-  find_package(Kokkos 3.2.00 REQUIRED CONFIG)
+  find_package(Kokkos 3.3.01 REQUIRED CONFIG)
   target_link_libraries(lammps PRIVATE Kokkos::kokkos)
 else()
   set(LAMMPS_LIB_KOKKOS_SRC_DIR ${LAMMPS_LIB_SOURCE_DIR}/kokkos)

cmake/Modules/Packages/MESSAGE.cmake

@@ -2,9 +2,8 @@ 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/[^.]*.F
-    ${LAMMPS_LIB_SOURCE_DIR}/message/cslib/[^.]*.c
-    ${LAMMPS_LIB_SOURCE_DIR}/message/cslib/[^.]*.cpp)
+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})

cmake/Modules/Packages/MLIAP.cmake

@@ -0,0 +1,40 @@
+# if PYTHON package is included we may also include Python support in MLIAP
+set(MLIAP_ENABLE_PYTHON_DEFAULT OFF)
+if(PKG_PYTHON)
+  find_package(Cythonize QUIET)
+  if(Cythonize_FOUND)
+    set(MLIAP_ENABLE_PYTHON_DEFAULT ON)
+  endif()
+endif()
+
+option(MLIAP_ENABLE_PYTHON "Build MLIAP package with Python support" ${MLIAP_ENABLE_PYTHON_DEFAULT})
+
+if(MLIAP_ENABLE_PYTHON)
+  find_package(Cythonize REQUIRED)
+  if(NOT PKG_PYTHON)
+    message(FATAL_ERROR "Must enable PYTHON package for including Python support in MLIAP")
+  endif()
+  if(CMAKE_VERSION VERSION_LESS 3.12)
+    if(PYTHONLIBS_VERSION_STRING VERSION_LESS 3.6)
+      message(FATAL_ERROR "Python support in MLIAP requires Python 3.6 or later")
+    endif()
+  else()
+    if(Python_VERSION VERSION_LESS 3.6)
+      message(FATAL_ERROR "Python support in MLIAP requires Python 3.6 or later")
+    endif()
+  endif()
+
+  set(MLIAP_BINARY_DIR ${CMAKE_BINARY_DIR}/cython)
+  set(MLIAP_CYTHON_SRC ${LAMMPS_SOURCE_DIR}/MLIAP/mliap_model_python_couple.pyx)
+  get_filename_component(MLIAP_CYTHON_BASE ${MLIAP_CYTHON_SRC} NAME_WE)
+  file(MAKE_DIRECTORY ${MLIAP_BINARY_DIR})
+  add_custom_command(OUTPUT  ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.cpp ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.h
+          COMMAND            ${CMAKE_COMMAND} -E copy_if_different ${MLIAP_CYTHON_SRC} ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.pyx
+          COMMAND            ${Cythonize_EXECUTABLE} -3 ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.pyx
+          WORKING_DIRECTORY  ${MLIAP_BINARY_DIR}
+          MAIN_DEPENDENCY    ${MLIAP_CYTHON_SRC}
+          COMMENT "Generating C++ sources with cythonize...")
+  target_compile_definitions(lammps PRIVATE -DMLIAP_PYTHON)
+  target_sources(lammps PRIVATE ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.cpp)
+  target_include_directories(lammps PRIVATE ${MLIAP_BINARY_DIR})
+endif()

cmake/Modules/Packages/USER-PLUMED.cmake

@@ -55,8 +55,8 @@ if(DOWNLOAD_PLUMED)
   endif()
   include(ExternalProject)
   ExternalProject_Add(plumed_build
-    URL https://github.com/plumed/plumed2/releases/download/v2.6.1/plumed-src-2.6.1.tgz
-    URL_MD5 89a9a450fc6025299fe16af235957163
+    URL https://github.com/plumed/plumed2/releases/download/v2.7.0/plumed-src-2.7.0.tgz
+    URL_MD5 95f29dd0c067577f11972ff90dfc7d12
     BUILD_IN_SOURCE 1
     CONFIGURE_COMMAND <SOURCE_DIR>/configure --prefix=<INSTALL_DIR>
                                              ${CONFIGURE_REQUEST_PIC}

cmake/Modules/YAML.cmake

@@ -0,0 +1,32 @@
+message(STATUS "Downloading and building YAML library")
+
+include(ExternalProject)
+set(YAML_URL "https://pyyaml.org/download/libyaml/yaml-0.2.5.tar.gz" CACHE STRING "URL for libyaml tarball")
+mark_as_advanced(YAML_URL)
+ExternalProject_Add(libyaml
+                    URL               ${YAML_URL}
+                    URL_MD5           bb15429d8fb787e7d3f1c83ae129a999
+                    SOURCE_DIR        "${CMAKE_BINARY_DIR}/yaml-src"
+                    BINARY_DIR        "${CMAKE_BINARY_DIR}/yaml-build"
+                    CONFIGURE_COMMAND <SOURCE_DIR>/configure ${CONFIGURE_REQUEST_PIC}
+                                      CXX=${CMAKE_CXX_COMPILER}
+                                      CC=${CMAKE_C_COMPILER}
+                                      --prefix=<INSTALL_DIR> --disable-shared
+                    BUILD_BYPRODUCTS  <INSTALL_DIR>/lib/libyaml${CMAKE_STATIC_LIBRARY_SUFFIX}
+                    TEST_COMMAND      "")
+
+ExternalProject_Get_Property(libyaml INSTALL_DIR)
+set(YAML_INCLUDE_DIR ${INSTALL_DIR}/include)
+set(YAML_LIBRARY_DIR ${INSTALL_DIR}/lib)
+
+# workaround for CMake 3.10 on ubuntu 18.04
+file(MAKE_DIRECTORY ${YAML_INCLUDE_DIR})
+file(MAKE_DIRECTORY ${YAML_LIBRARY_DIR})
+
+set(YAML_LIBRARY_PATH ${INSTALL_DIR}/lib/libyaml${CMAKE_STATIC_LIBRARY_SUFFIX})
+
+add_library(Yaml::Yaml UNKNOWN IMPORTED)
+set_target_properties(Yaml::Yaml PROPERTIES
+        IMPORTED_LOCATION ${YAML_LIBRARY_PATH}
+        INTERFACE_INCLUDE_DIRECTORIES ${YAML_INCLUDE_DIR})
+add_dependencies(Yaml::Yaml libyaml)

cmake/presets/pgi.cmake

@@ -0,0 +1,16 @@
+# preset that will enable clang/clang++ 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)
+set(CMAKE_Fortran_COMPILER "pgfortran" CACHE STRING "" FORCE)
+set(MPI_CXX "pgc++" CACHE STRING "" FORCE)
+set(MPI_CXX_COMPILER "mpicxx" CACHE STRING "" FORCE)
+unset(HAVE_OMP_H_INCLUDE CACHE)
+
+set(OpenMP_C "pgcc" CACHE STRING "" FORCE)
+set(OpenMP_C_FLAGS "-mp" CACHE STRING "" FORCE)
+set(OpenMP_C_LIB_NAMES "omp" CACHE STRING "" FORCE)
+set(OpenMP_CXX "pgc++" CACHE STRING "" FORCE)
+set(OpenMP_CXX_FLAGS "-mp" CACHE STRING "" FORCE)
+set(OpenMP_CXX_LIB_NAMES "omp" CACHE STRING "" FORCE)
+set(OpenMP_omp_LIBRARY "libomp.so" CACHE PATH "" FORCE)

doc/Makefile

@@ -47,6 +47,8 @@ HAS_PDFLATEX = YES
 endif
 endif
 
+# override settings for PIP commands
+# PIP_OPTIONS = --cert /etc/pki/ca-trust/extracted/openssl/ca-bundle.trust.crt --proxy http://proxy.mydomain.org
 
 #SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())') $(shell test -f $(BUILDDIR)/doxygen/xml/run.stamp && printf -- "-E")
 
@@ -94,7 +96,7 @@ $(SPHINXCONFIG)/conf.py: $(SPHINXCONFIG)/conf.py.in
 	    -e 's,@LAMMPS_PYTHON_DIR@,$(BUILDDIR)/../python,g' \
 	    -e 's,@LAMMPS_DOC_DIR@,$(BUILDDIR),g' $< > $@
 
-html: xmlgen $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX)
+html: 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
 	@(\
@@ -118,7 +120,7 @@ html: xmlgen $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX)
 	@rm -rf html/PDF/.[sg]*
 	@echo "Build finished. The HTML pages are in doc/html."
 
-spelling: xmlgen $(VENV) $(SPHINXCONFIG)/false_positives.txt
+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
 	@(\
 		. $(VENV)/bin/activate ; env PYTHONWARNINGS= \
@@ -228,13 +230,13 @@ $(VENV):
 	@( \
 		$(VIRTUALENV) -p $(PYTHON) $(VENV); \
 		. $(VENV)/bin/activate; \
-		pip install --upgrade pip; \
-		pip install --use-feature=2020-resolver -r $(BUILDDIR)/utils/requirements.txt; \
+		pip $(PIP_OPTIONS) install --upgrade pip; \
+		pip $(PIP_OPTIONS) install -r $(BUILDDIR)/utils/requirements.txt; \
 		deactivate;\
 	)
 
 $(MATHJAX):
-	@git clone --depth 1 https://github.com/mathjax/MathJax.git $@
+	@git clone --depth 1 git://github.com/mathjax/MathJax.git $@
 
 $(TXT2RST) $(ANCHORCHECK): $(VENV)
 	@( \

doc/doxygen/Doxyfile.in

@@ -424,6 +424,8 @@ INPUT                  = @LAMMPS_SOURCE_DIR@/utils.cpp                 \
                          @LAMMPS_SOURCE_DIR@/input.h                   \
                          @LAMMPS_SOURCE_DIR@/tokenizer.cpp             \
                          @LAMMPS_SOURCE_DIR@/tokenizer.h               \
+                         @LAMMPS_SOURCE_DIR@/arg_info.cpp              \
+                         @LAMMPS_SOURCE_DIR@/arg_info.h                \
                          @LAMMPS_SOURCE_DIR@/text_file_reader.cpp      \
                          @LAMMPS_SOURCE_DIR@/text_file_reader.h        \
                          @LAMMPS_SOURCE_DIR@/potential_file_reader.cpp \

doc/github-development-workflow.md

@@ -95,7 +95,7 @@ on the pull request discussion page on GitHub, so that other developers
 can later review the entire discussion after the fact and understand the
 rationale behind choices made.  Exceptions to this policy are technical
 discussions, that are centered on tools or policies themselves
-(git, github, c++) rather than on the content of the pull request.
+(git, GitHub, c++) rather than on the content of the pull request.
 
 ### Checklist for Pull Requests
 

doc/lammps.1

@@ -1,4 +1,4 @@
-.TH LAMMPS "29 October 2020" "2020-10-29"
+.TH LAMMPS "10 March 2021" "2021-03-10"
 .SH NAME
 .B LAMMPS
 \- Molecular Dynamics Simulator.

doc/src/Build_basics.rst

@@ -95,7 +95,7 @@ standard. A more detailed discussion of that is below.
 
       .. note::
 
-         The file ``src/STUBS/mpi.c`` provides a CPU timer function
+         The file ``src/STUBS/mpi.cpp`` provides a CPU timer function
          called ``MPI_Wtime()`` that calls ``gettimeofday()``.  If your
          operating system does not support ``gettimeofday()``, you will
          need to insert code to call another timer.  Note that the
@@ -236,12 +236,15 @@ LAMMPS.
          cmake ../cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort
          # Building with LLVM/Clang Compilers:
          cmake ../cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_Fortran_COMPILER=flang
+         # Building with PGI/Nvidia Compilers:
+         cmake ../cmake -DCMAKE_C_COMPILER=pgcc -DCMAKE_CXX_COMPILER=pgc++ -DCMAKE_Fortran_COMPILER=pgfortran
 
       For compiling with the Clang/LLVM compilers a CMake preset is
       provided that can be loaded with
       `-C ../cmake/presets/clang.cmake`.  Similarly,
       `-C ../cmake/presets/intel.cmake` should switch the compiler
-      toolchain to the Intel compilers.
+      toolchain to the Intel compilers and `-C ../cmake/presets/pgi.cmake`
+      should switch the compiler to the PGI compilers.
 
       In addition you can set ``CMAKE_TUNE_FLAGS`` to specifically add
       compiler flags to tune for optimal performance on given hosts. By
@@ -523,6 +526,20 @@ you want to copy files to is protected.
          make                        # perform make after CMake command
          make install                # perform the installation into prefix
 
+      During the installation process CMake will by default remove any runtime
+      path settings for loading shared libraries.  Because of this you may
+      have to set or modify the ``LD_LIBRARY_PATH`` (or ``DYLD_LIBRARY_PATH``)
+      environment variable, if you are installing LAMMPS into a non-system
+      location and/or are linking to libraries in a non-system location that
+      depend on such runtime path settings.
+      As an alternative you may set the CMake variable ``LAMMPS_INSTALL_RPATH``
+      to ``on`` and then the runtime paths for any linked shared libraries
+      and the library installation folder for the LAMMPS library will be
+      embedded and thus the requirement to set environment variables is avoided.
+      The ``off`` setting is usually preferred for packaged binaries or when
+      setting up environment modules, the ``on`` setting is more convenient
+      for installing software into a non-system or personal folder.
+
    .. tab:: Traditional make
 
       There is no "install" option in the ``src/Makefile`` for LAMMPS.

doc/src/Build_development.rst

@@ -108,11 +108,18 @@ results over a given number of steps and operations within a given
 error margin).  The status of this automated testing can be viewed on
 `https://ci.lammps.org <https://ci.lammps.org>`_.
 
+The scripts and inputs for integration, run, and regression testing
+are maintained in a
+`separate repository <https://github.com/lammps/lammps-testing>`_
+of the LAMMPS project on GitHub.
+
 The unit testing facility is integrated into the CMake build process
 of the LAMMPS source code distribution itself.  It can be enabled by
 setting ``-D ENABLE_TESTING=on`` during the CMake configuration step.
-It requires the `PyYAML <http://pyyaml.org/>`_ library and development
-headers to compile and will download and compile a recent version of the
+It requires the `YAML <http://pyyaml.org/>`_ library and development
+headers (if those are not found locally a recent version will be
+downloaded and compiled along with LAMMPS and the test program) to
+compile and will download and compile a specific recent version of the
 `Googletest <https://github.com/google/googletest/>`_ C++ test framework
 for implementing the tests.
 
@@ -162,22 +169,21 @@ The ``ctest`` command has many options, the most important ones are:
 In its full implementation, the unit test framework will consist of multiple
 kinds of tests implemented in different programming languages (C++, C, Python,
 Fortran) and testing different aspects of the LAMMPS software and its features.
-At the moment only tests for "force styles" are implemented. More on those
-in the next section.
+The tests will adapt to the compilation settings of LAMMPS, so that tests
+will be skipped if prerequisite features are not available in LAMMPS.
 
 .. note::
 
-   The unit test framework is new and still under development.
-   The coverage is only minimal and will be expanded over time.
-   Tests styles of the same kind of style (e.g. pair styles or
-   bond styles) are performed with the same executable using
-   different input files in YAML format.  So to add a test for
-   another pair style can be done by copying the YAML file and
-   editing the style settings and then running the individual test
-   program with a flag to update the computed reference data.
-   Detailed documentation about how to add new test program and
-   the contents of the YAML files for existing test programs
-   will be provided in time as well.
+   The unit test framework was added in spring 2020 and is under active
+   development.  The coverage is not complete and will be expanded over
+   time.
+
+Tests for styles of the same kind of style (e.g. pair styles or bond
+styles) are performed with the same test executable using different
+input files in YAML format.  So to add a test for another style of the
+same kind it may be sufficient to add a suitable YAML file.
+:doc:`Detailed instructions for adding tests <Developer_unittest>` are
+provided in the Programmer Guide part of the manual.
 
 Unit tests for force styles
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^

doc/src/Build_extras.rst

@@ -37,6 +37,7 @@ This is the list of packages that may require additional steps.
    * :ref:`KOKKOS <kokkos>`
    * :ref:`LATTE <latte>`
    * :ref:`MESSAGE <message>`
+   * :ref:`MLIAP <mliap>`
    * :ref:`MSCG <mscg>`
    * :ref:`OPT <opt>`
    * :ref:`POEMS <poems>`
@@ -119,8 +120,6 @@ CMake build
    -D GPU_API=value             # value = opencl (default) or cuda or hip
    -D GPU_PREC=value            # precision setting
                                 # value = double or mixed (default) or single
-   -D OCL_TUNE=value            # hardware choice for GPU_API=opencl
-                                # generic (default) or intel (Intel CPU) or fermi, kepler, cypress (NVIDIA)
    -D GPU_ARCH=value            # primary GPU hardware choice for GPU_API=cuda
                                 # value = sm_XX, see below
                                 # default is sm_50
@@ -130,10 +129,12 @@ CMake build
    -D HIP_USE_DEVICE_SORT=value # enables GPU sorting
                                 # value = yes (default) or no
    -D CUDPP_OPT=value           # optimization setting for GPU_API=cuda
-                                # enables CUDA Performance Primitives Optimizations
+                                # enables CUDA Performance Primitives Optimizations, must be "no" for CUDA_MPS_SUPPORT=yes
                                 # value = yes (default) or no
    -D CUDA_MPS_SUPPORT=value    # enables some tweaks required to run with active nvidia-cuda-mps daemon
                                 # value = yes or no (default)
+   -D USE_STATIC_OPENCL_LOADER=value  # downloads/includes OpenCL ICD loader library, no local OpenCL headers/libs needed
+                                      # value = yes (default) or no
 
 :code:`GPU_ARCH` settings for different GPU hardware is as follows:
 
@@ -160,6 +161,12 @@ 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.
 
+If you are compiling for OpenCL, the default setting is to download, build, and
+link with a static OpenCL ICD loader library and standard OpenCL headers.  This
+way no local OpenCL development headers or library needs to be present and only
+OpenCL compatible drivers need to be installed to use OpenCL.  If this is not
+desired, you can set :code:`USE_STATIC_OPENCL_LOADER` to :code:`no`.
+
 If you are compiling with HIP, note that before running CMake you will have to
 set appropriate environment variables. Some variables such as
 :code:`HCC_AMDGPU_TARGET` or :code:`CUDA_PATH` are necessary for :code:`hipcc`
@@ -218,11 +225,19 @@ Makefile if desired:
 * ``CUDA_PRECISION`` = precision (double, mixed, single)
 * ``EXTRAMAKE`` = which Makefile.lammps.\* file to copy to Makefile.lammps
 
-The file Makefile.linux_multi is set up to include support for multiple
+The file Makefile.cuda is set up to include support for multiple
 GPU architectures as supported by the CUDA toolkit in use. This is done
 through using the "--gencode " flag, which can be used multiple times and
 thus support all GPU architectures supported by your CUDA compiler.
 
+To include CUDA performance primitives set the Makefile variable
+``CUDPP_OPT = -DUSE_CUDPP -Icudpp_mini``.
+
+To support the CUDA multiprocessor server you can set the define
+``-DCUDA_PROXY``.  Please note that in this case you should **not** use
+the CUDA performance primitives and thus set the variable ``CUDPP_OPT``
+to empty.
+
 If the library build is successful, 3 files should be created:
 ``lib/gpu/libgpu.a``\ , ``lib/gpu/nvc_get_devices``\ , and
 ``lib/gpu/Makefile.lammps``\ .  The latter has settings that enable LAMMPS
@@ -249,18 +264,18 @@ To build with this package, the KIM library with API v2 must be downloaded
 and built on your system. It must include the KIM models that you want to
 use with LAMMPS.
 
-If you would like to use the :doc:`kim_query <kim_commands>`
+If you would like to use the :doc:`kim query <kim_commands>`
 command, you also need to have libcurl installed with the matching
 development headers and the curl-config tool.
 
-If you would like to use the :doc:`kim_property <kim_commands>`
+If you would like to use the :doc:`kim property <kim_commands>`
 command, you need to build LAMMPS with the PYTHON package installed
 and linked to Python 3.6 or later. See the :ref:`PYTHON package build info <python>`
 for more details on this. After successfully building LAMMPS with Python, you
-also need to install the kim-property Python package, which can be easily done using
-*pip* as ``pip install kim-property``, or from the *conda-forge* channel as
-``conda install kim-property`` if LAMMPS is built in Conda. More detailed
-information is available at:
+also need to install the ``kim-property`` Python package, which can be easily
+done using *pip* as ``pip install kim-property``, or from the *conda-forge*
+channel as ``conda install kim-property`` if LAMMPS is built in Conda. More
+detailed information is available at:
 `kim-property installation <https://github.com/openkim/kim-property#installing-kim-property>`_.
 
 In addition to installing the KIM API, it is also necessary to install the
@@ -282,6 +297,7 @@ minutes to hours) to build.  Of course you only need to do that once.)
          -D DOWNLOAD_KIM=value           # download OpenKIM API v2 for build, value = no (default) or yes
          -D LMP_DEBUG_CURL=value         # set libcurl verbose mode on/off, value = off (default) or on
          -D LMP_NO_SSL_CHECK=value       # tell libcurl to not verify the peer, value = no (default) or yes
+         -D KIM_EXTRA_UNITTESTS=value    # enables extra unit tests, value = no (default) or yes
 
       If ``DOWNLOAD_KIM`` is set to *yes* (or *on*), the KIM API library
       will be downloaded and built inside the CMake build directory.  If
@@ -290,11 +306,16 @@ minutes to hours) to build.  Of course you only need to do that once.)
       ``PKG_CONFIG_PATH`` environment variable so that libkim-api can be
       found, or run the command ``source kim-api-activate``.
 
+      Extra unit tests can only be available if they are explicitly requested
+      (``KIM_EXTRA_UNITTESTS`` is set to *yes* (or *on*)) and the prerequisites
+      are met. See :ref:`KIM Extra unit tests <kim_extra_unittests>` for
+      more details on this.
+
    .. tab:: Traditional make
 
       You can download and build the KIM library manually if you prefer;
       follow the instructions in ``lib/kim/README``.  You can also do
-      this in one step from the lammps/src dir, using a command like
+      this in one step from the lammps/src directory, using a command like
       these, which simply invoke the ``lib/kim/Install.py`` script with
       the specified args.
 
@@ -314,7 +335,7 @@ minutes to hours) to build.  Of course you only need to do that once.)
 
       .. code-block:: make
 
-         LMP_INC =       -DLMP_NO_SSL_CHECK
+         LMP_INC = -DLMP_NO_SSL_CHECK
 
 Debugging OpenKIM web queries in LAMMPS
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -338,6 +359,39 @@ specify your own CA cert path by setting the environment variable
 ``CURL_CA_BUNDLE`` to the path of your choice.  A call to the KIM web
 query would get this value from the environment variable.
 
+.. _kim_extra_unittests:
+
+KIM Extra unit tests (CMake only)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+During development, testing, or debugging, if
+:doc:`unit testing <Build_development>` is enabled in LAMMPS, one can also
+enable extra tests on :doc:`KIM commands <kim_commands>` by setting the
+``KIM_EXTRA_UNITTESTS`` to *yes* (or *on*).
+
+Enabling the extra unit tests have some requirements,
+
+* It requires to have internet access.
+* It requires to have libcurl installed with the matching development headers
+  and the curl-config tool.
+* It requires to build LAMMPS with the PYTHON package installed and linked to
+  Python 3.6 or later. See the :ref:`PYTHON package build info <python>` for
+  more details on this.
+* It requires to have ``kim-property`` Python package installed, which can be
+  easily done using *pip* as ``pip install kim-property``, or from the
+  *conda-forge* channel as ``conda install kim-property`` if LAMMPS is built in
+  Conda. More detailed information is available at:
+  `kim-property installation <https://github.com/openkim/kim-property#installing-kim-property>`_.
+* It is also necessary to install
+  ``EAM_Dynamo_MendelevAckland_2007v3_Zr__MO_004835508849_000``,
+  ``EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005``, and
+  ``LennardJones612_UniversalShifted__MO_959249795837_003`` KIM models.
+  See `Obtaining KIM Models <http://openkim.org/doc/usage/obtaining-models>`_
+  to learn how to install a pre-built binary of the OpenKIM Repository of
+  Models or see
+  `Installing KIM Models <https://openkim.org/doc/usage/obtaining-models/#installing_models>`_
+  to learn how to install the specific KIM models.
+
 ----------
 
 .. _kokkos:
@@ -482,11 +536,14 @@ They must be specified in uppercase.
    *  - VEGA906
       - GPU
       - AMD GPU MI50/MI60 GFX906
+   *  - VEGA908
+      - GPU
+      - AMD GPU GFX908
    *  - INTEL_GEN
       - GPU
       - Intel GPUs Gen9+
 
-This list was last updated for version 3.2 of the Kokkos library.
+This list was last updated for version 3.3 of the Kokkos library.
 
 .. tabs::
 
@@ -732,6 +789,54 @@ be installed on your system.
 
 ----------
 
+.. _mliap:
+
+MLIAP package
+---------------------------
+
+Building the MLIAP package requires including the :ref:`SNAP <PKG-SNAP>`
+package.  There will be an error message if this requirement is not satisfied.
+Using the *mliappy* model also requires enabling Python support, which
+in turn requires the :ref:`PYTHON <PKG-PYTHON>`
+package **and** requires you have the `cython <https://cython.org>`_ software
+installed and with it a working ``cythonize`` command.  This feature requires
+compiling LAMMPS with Python version 3.6 or later.
+
+.. tabs::
+
+   .. tab:: CMake build
+
+      .. code-block:: bash
+
+         -D MLIAP_ENABLE_PYTHON=value   # enable mliappy model (default is autodetect)
+
+      Without this setting, CMake will check whether it can find a
+      suitable Python version and the ``cythonize`` command and choose
+      the default accordingly.  During the build procedure the provided
+      .pyx file(s) will be automatically translated to C++ code and compiled.
+      Please do **not** run ``cythonize`` manually in the ``src/MLIAP`` folder,
+      as that can lead to compilation errors if Python support is not enabled.
+      If you did by accident, please remove the generated .cpp and .h files.
+
+   .. tab:: Traditional make
+
+      The build uses the ``lib/python/Makefile.mliap_python`` file in the
+      compile/link process to add a rule to update the files generated by
+      the ``cythonize`` command in case the corresponding .pyx file(s) were
+      modified.  You may need to modify ``lib/python/Makefile.lammps``
+      if the LAMMPS build fails.
+      To manually enforce building MLIAP with Python support enabled,
+      you can add
+      ``-DMLIAP_PYTHON`` to the ``LMP_INC`` variable in your machine makefile.
+      You may have to manually run the ``cythonize`` command on .pyx file(s)
+      in the ``src`` folder, if this is not automatically done during
+      installing the MLIAP package.  Please do **not** run ``cythonize``
+      in the ``src/MLIAP`` folder, as that can lead to compilation errors
+      if Python support is not enabled.
+      If you did by accident, please remove the generated .cpp and .h files.
+
+----------
+
 .. _mscg:
 
 MSCG package

doc/src/Build_link.rst

@@ -20,16 +20,8 @@ the suffix ``.so.0`` (or some other number).
 .. note::
 
    Care should be taken to use the same MPI library for the calling code
-   and the LAMMPS library.  The ``library.h`` file includes ``mpi.h``
-   and uses definitions from it so those need to be available and
-   consistent.  When LAMMPS is compiled with the included STUBS MPI
-   library, then its ``mpi.h`` file needs to be included.  While it is
-   technically possible to use a full MPI library in the calling code
-   and link to a serial LAMMPS library compiled with MPI STUBS, it is
-   recommended to use the *same* MPI library for both, and then use
-   ``MPI_Comm_split()`` in the calling code to pass a suitable
-   communicator with a subset of MPI ranks to the function creating the
-   LAMMPS instance.
+   and the LAMMPS library unless LAMMPS is to be compiled without (real)
+   MPI support using the include STUBS MPI library.
 
 Link with LAMMPS as a static library
 ------------------------------------
@@ -110,7 +102,7 @@ executable, that are also required to link the LAMMPS executable.
 
       .. code-block:: bash
 
-         gcc -c -O -I${HOME}/lammps/src/STUBS -I${HOME}/lammps/src -caller.c
+         gcc -c -O -I${HOME}/lammps/src -caller.c
          g++ -o caller caller.o -L${HOME}/lammps/lib/poems \
                       -L${HOME}/lammps/src/STUBS -L${HOME}/lammps/src \
                       -llammps_serial -lpoems -lmpi_stubs
@@ -174,7 +166,7 @@ the POEMS package installed becomes:
 
       .. code-block:: bash
 
-         gcc -c -O -I${HOME}/lammps/src/STUBS -I${HOME}/lammps/src -caller.c
+         gcc -c -O -I${HOME}/lammps/src -caller.c
          g++ -o caller caller.o -L${HOME}/lammps/src -llammps_serial
 
 Locating liblammps.so at runtime

doc/src/Build_manual.rst

@@ -74,7 +74,11 @@ For the documentation build a python virtual environment is set up in
 the folder ``doc/docenv`` and various python packages are installed into
 that virtual environment via the ``pip`` tool.  For rendering embedded
 LaTeX code also the `MathJax <https://www.mathjax.org/>`_ JavaScript
-engine needs to be downloaded.
+engine needs to be downloaded.  If you need to pass additional options
+to the pip commands to work (e.g. to use a web proxy or to point to
+additional SSL certificates) you can set them via the ``PIP_OPTIONS``
+environment variable or uncomment and edit the ``PIP_OPTIONS`` setting
+at beginning of the makefile.
 
 The actual translation is then done via ``make`` commands in the doc
 folder.  The following ``make`` commands are available:
@@ -108,7 +112,10 @@ installation of the HTML manual pages into the "install" step when
 installing LAMMPS after the CMake build via ``cmake --build . --target
 install``.  The documentation build is included in the default build
 target, but can also be requested independently with
-``cmake --build . --target doc``.
+``cmake --build . --target doc``.  If you need to pass additional options
+to the pip commands to work (e.g. to use a web proxy or to point to
+additional SSL certificates) you can set them via the ``PIP_OPTIONS``
+environment variable.
 
 .. code-block:: bash
 

doc/src/Build_package.rst

@@ -160,6 +160,7 @@ one of them as a starting point and customize it to your needs.
     cmake -C ../cmake/presets/clang.cmake    [OPTIONS] ../cmake  # change settings to use the Clang compilers by default
     cmake -C ../cmake/presets/gcc.cmake      [OPTIONS] ../cmake  # change settings to use the GNU compilers by default
     cmake -C ../cmake/presets/intel.cmake    [OPTIONS] ../cmake  # change settings to use the Intel compilers by default
+    cmake -C ../cmake/presets/pgi.cmake      [OPTIONS] ../cmake  # change settings to use the PGI compilers by default
     cmake -C ../cmake/presets/all_on.cmake   [OPTIONS] ../cmake  # enable all packages
     cmake -C ../cmake/presets/all_off.cmake  [OPTIONS] ../cmake  # disable all packages
     mingw64-cmake -C ../cmake/presets/mingw-cross.cmake [OPTIONS] ../cmake  #  compile with MinGW cross compilers

doc/src/Commands_all.rst

@@ -60,11 +60,7 @@ An alphabetic list of all general LAMMPS commands.
    * :doc:`include <include>`
    * :doc:`info <info>`
    * :doc:`jump <jump>`
-   * :doc:`kim_init <kim_commands>`
-   * :doc:`kim_interactions <kim_commands>`
-   * :doc:`kim_param <kim_commands>`
-   * :doc:`kim_property <kim_commands>`
-   * :doc:`kim_query <kim_commands>`
+   * :doc:`kim <kim_commands>`
    * :doc:`kspace_modify <kspace_modify>`
    * :doc:`kspace_style <kspace_style>`
    * :doc:`label <label>`

doc/src/Commands_bond.rst

@@ -35,6 +35,7 @@ OPT.
    * :doc:`class2 (ko) <bond_class2>`
    * :doc:`fene (iko) <bond_fene>`
    * :doc:`fene/expand (o) <bond_fene_expand>`
+   * :doc:`gaussian <bond_gaussian>`
    * :doc:`gromos (o) <bond_gromos>`
    * :doc:`harmonic (iko) <bond_harmonic>`
    * :doc:`harmonic/shift (o) <bond_harmonic_shift>`
@@ -84,6 +85,7 @@ OPT.
    * :doc:`dipole (o) <angle_dipole>`
    * :doc:`fourier (o) <angle_fourier>`
    * :doc:`fourier/simple (o) <angle_fourier_simple>`
+   * :doc:`gaussian <angle_gaussian>` - multicentered Gaussian-based angle potential
    * :doc:`harmonic (iko) <angle_harmonic>`
    * :doc:`mm3 <angle_mm3>`
    * :doc:`quartic (o) <angle_quartic>`

doc/src/Commands_fix.rst

@@ -62,6 +62,7 @@ OPT.
    * :doc:`efield <fix_efield>`
    * :doc:`ehex <fix_ehex>`
    * :doc:`electron/stopping <fix_electron_stopping>`
+   * :doc:`electron/stopping/fit <fix_electron_stopping>`
    * :doc:`enforce2d (k) <fix_enforce2d>`
    * :doc:`eos/cv <fix_eos_cv>`
    * :doc:`eos/table <fix_eos_table>`
@@ -113,7 +114,7 @@ OPT.
    * :doc:`nph/eff <fix_nh_eff>`
    * :doc:`nph/sphere (o) <fix_nph_sphere>`
    * :doc:`nphug <fix_nphug>`
-   * :doc:`npt (iko) <fix_nh>`
+   * :doc:`npt (giko) <fix_nh>`
    * :doc:`npt/asphere (o) <fix_npt_asphere>`
    * :doc:`npt/body <fix_npt_body>`
    * :doc:`npt/cauchy <fix_npt_cauchy>`
@@ -121,8 +122,8 @@ OPT.
    * :doc:`npt/sphere (o) <fix_npt_sphere>`
    * :doc:`npt/uef <fix_nh_uef>`
    * :doc:`numdiff <fix_numdiff>`
-   * :doc:`nve (iko) <fix_nve>`
-   * :doc:`nve/asphere (i) <fix_nve_asphere>`
+   * :doc:`nve (giko) <fix_nve>`
+   * :doc:`nve/asphere (gi) <fix_nve_asphere>`
    * :doc:`nve/asphere/noforce <fix_nve_asphere_noforce>`
    * :doc:`nve/awpmd <fix_nve_awpmd>`
    * :doc:`nve/body <fix_nve_body>`
@@ -137,7 +138,7 @@ OPT.
    * :doc:`nve/spin <fix_nve_spin>`
    * :doc:`nve/tri <fix_nve_tri>`
    * :doc:`nvk <fix_nvk>`
-   * :doc:`nvt (iko) <fix_nh>`
+   * :doc:`nvt (giko) <fix_nh>`
    * :doc:`nvt/asphere (o) <fix_nvt_asphere>`
    * :doc:`nvt/body <fix_nvt_body>`
    * :doc:`nvt/eff <fix_nh_eff>`
@@ -195,7 +196,7 @@ OPT.
    * :doc:`saed/vtk <fix_saed_vtk>`
    * :doc:`setforce (k) <fix_setforce>`
    * :doc:`setforce/spin <fix_setforce>`
-   * :doc:`shake <fix_shake>`
+   * :doc:`shake (k) <fix_shake>`
    * :doc:`shardlow (k) <fix_shardlow>`
    * :doc:`smd <fix_smd>`
    * :doc:`smd/adjust_dt <fix_smd_adjust_dt>`
@@ -220,6 +221,8 @@ OPT.
    * :doc:`temp/rescale <fix_temp_rescale>`
    * :doc:`temp/rescale/eff <fix_temp_rescale_eff>`
    * :doc:`tfmc <fix_tfmc>`
+   * :doc:`tgnpt/drude <fix_tgnh_drude>`
+   * :doc:`tgnvt/drude <fix_tgnh_drude>`
    * :doc:`thermal/conductivity <fix_thermal_conductivity>`
    * :doc:`ti/spring <fix_ti_spring>`
    * :doc:`tmd <fix_tmd>`

doc/src/Commands_pair.rst

@@ -96,6 +96,7 @@ OPT.
    * :doc:`eam/cd <pair_eam>`
    * :doc:`eam/cd/old <pair_eam>`
    * :doc:`eam/fs (gikot) <pair_eam>`
+   * :doc:`eam/he <pair_eam>`
    * :doc:`edip (o) <pair_edip>`
    * :doc:`edip/multi <pair_edip>`
    * :doc:`edpd <pair_mesodpd>`
@@ -121,7 +122,7 @@ OPT.
    * :doc:`lebedeva/z <pair_lebedeva_z>`
    * :doc:`lennard/mdf <pair_mdf>`
    * :doc:`line/lj <pair_line_lj>`
-   * :doc:`lj/charmm/coul/charmm (iko) <pair_charmm>`
+   * :doc:`lj/charmm/coul/charmm (giko) <pair_charmm>`
    * :doc:`lj/charmm/coul/charmm/implicit (ko) <pair_charmm>`
    * :doc:`lj/charmm/coul/long (gikot) <pair_charmm>`
    * :doc:`lj/charmm/coul/long/soft (o) <pair_fep_soft>`
@@ -162,6 +163,7 @@ OPT.
    * :doc:`lj/long/dipole/long <pair_dipole>`
    * :doc:`lj/long/tip4p/long (o) <pair_lj_long>`
    * :doc:`lj/mdf <pair_mdf>`
+   * :doc:`lj/relres (o) <pair_lj_relres>`
    * :doc:`lj/sdk (gko) <pair_sdk>`
    * :doc:`lj/sdk/coul/long (go) <pair_sdk>`
    * :doc:`lj/sdk/coul/msm (o) <pair_sdk>`
@@ -241,6 +243,7 @@ OPT.
    * :doc:`spin/dipole/long <pair_spin_dipole>`
    * :doc:`spin/dmi <pair_spin_dmi>`
    * :doc:`spin/exchange <pair_spin_exchange>`
+   * :doc:`spin/exchange/biquadratic <pair_spin_exchange>`
    * :doc:`spin/magelec <pair_spin_magelec>`
    * :doc:`spin/neel <pair_spin_neel>`
    * :doc:`srp <pair_srp>`
@@ -261,6 +264,7 @@ OPT.
    * :doc:`ufm (got) <pair_ufm>`
    * :doc:`vashishta (gko) <pair_vashishta>`
    * :doc:`vashishta/table (o) <pair_vashishta>`
+   * :doc:`wf/cut <pair_wf_cut>`
    * :doc:`yukawa (gko) <pair_yukawa>`
    * :doc:`yukawa/colloid (go) <pair_yukawa_colloid>`
    * :doc:`zbl (gko) <pair_zbl>`

doc/src/Commands_parse.rst

@@ -162,3 +162,26 @@ LAMMPS:
    triple quotes can be nested in the usual manner.  See the doc pages
    for those commands for examples.  Only one of level of nesting is
    allowed, but that should be sufficient for most use cases.
+
+.. admonition:: ASCII versus UTF-8
+        :class: note
+
+   LAMMPS expects and processes 7-bit ASCII format text internally.
+   Many modern environments use UTF-8 encoding, which is a superset
+   of the 7-bit ASCII character table and thus mostly compatible.
+   However, there are several non-ASCII characters that can look
+   very similar to their ASCII equivalents or are invisible (so they
+   look like a blank), but are encoded differently.  Web browsers,
+   PDF viewers, document editors are known to sometimes replace one
+   with the other for a better looking output.  However, that can
+   lead to problems, for instance, when using cut-n-paste of input
+   file examples from web pages, or when using a document editor
+   (not a dedicated plain text editor) for writing LAMMPS inputs.
+   LAMMPS will try to detect this and substitute the non-ASCII
+   characters with their ASCII equivalents where known.  There also
+   is going to be a warning printed, if this occurs.  It is
+   recommended to avoid such characters altogether in LAMMPS input,
+   data and potential files.  The replacement tables are likely
+   incomplete and dependent on users reporting problems processing
+   correctly looking input containing UTF-8 encoded non-ASCII
+   characters.

doc/src/Developer.rst

@@ -13,5 +13,7 @@ of time and requests from the LAMMPS user community.
    Developer_org
    Developer_flow
    Developer_write
+   Developer_notes
+   Developer_unittest
    Classes
    Developer_utils

doc/src/Developer_notes.rst

@@ -0,0 +1,227 @@
+Notes for developers and code maintainers
+-----------------------------------------
+
+This section documents how some of the code functionality within
+LAMMPS works at a conceptual level.  Comments on code in source files
+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.
+
+Fix contributions to instantaneous energy, virial, and cumulative energy
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Fixes can calculate contributions to the instantaneous energy and/or
+virial of the system, both in a global and peratom sense.  Fixes that
+perform thermostatting or barostatting can calculate the cumulative
+energy they add to or subtract from the system, which is accessed by
+the *ecouple* and *econserve* thermodynamic keywords.  This subsection
+explains how both work and what flags to set in a new fix to enable
+this functionality.
+
+Let's start with thermostatting and barostatting fixes.  Examples are
+the :doc:`fix langevin <fix_langevin>` and :doc:`fix npt <fix_nh>`
+commands.  Here is what the fix needs to do:
+
+* Set the variable *ecouple_flag* = 1 in the constructor.  Also set
+  *scalar_flag* = 1, *extscalar* = 1, and *global_freq* to a timestep
+  increment which matches how often the fix is invoked.
+* Implement a compute_scalar() method that returns the cumulative
+  energy added or subtracted by the fix, e.g. by rescaling the
+  velocity of atoms.  The sign convention is that subtracted energy is
+  positive, added energy is negative.  This must be the total energy
+  added to the entire system, i.e. an "extensive" quantity, not a
+  per-atom energy.  Cumulative means the summed energy since the fix
+  was instantiated, even across multiple runs.  This is because the
+  energy is used by the *econserve* thermodynamic keyword to check
+  that the fix is conserving the total energy of the system,
+  i.e. potential energy + kinetic energy + coupling energy = a
+  constant.
+
+And here is how the code operates:
+
+* The Modify class makes a list of all fixes that set *ecouple_flag* = 1.
+* The :doc:`thermo_style custom <thermo_style>` command defines
+  *ecouple* and *econserve* keywords.
+* These keywords sum the energy contributions from all the
+  *ecouple_flag* = 1 fixes by invoking the energy_couple() method in
+  the Modify class, which calls the compute_scalar() method of each
+  fix in the list.
+
+------------------
+
+Next, here is how a fix contributes to the instantaneous energy and
+virial of the system.  First, it sets any or all of these flags to a
+value of 1 in their constructor:
+
+* *energy_global_flag* to contribute to global energy, example: :doc:`fix indent <fix_indent>`
+* *energy_peratom_flag* to contribute to peratom energy, :doc:`fix cmap <fix_cmap>`
+* *virial_global_flag* to contribute to global virial, example: :doc:`fix wall <fix_wall>`
+* *virial_peratom_flag* to contribute to peratom virial, example: :doc:`fix wall <fix_wall>`
+
+The fix must also do the following:
+
+* For global energy, implement a compute_scalar() method that returns
+  the energy added or subtracted on this timestep.  Here the sign
+  convention is that added energy is positive, subtracted energy is
+  negative.
+* For peratom energy, invoke the ev_init(eflag,vflag) function each
+  time the fix is invoked, which initializes per-atom energy storage.
+  The value of eflag may need to be stored from an earlier call to the
+  fix during the same timestep.  See how the :doc:`fix cmap
+  <fix_cmap>` command does this in src/MOLECULE/fix_cmap.cpp.  When an
+  energy for one or more atoms is calculated, invoke the ev_tally()
+  function to tally the contribution to each atom.  Both the ev_init()
+  and ev_tally() methods are in the parent Fix class.
+* For global and/or peratom virial, invoke the v_init(vflag) function
+  each time the fix is invoked, which initializes virial storage.
+  When forces on one or more atoms are calculated, invoke the
+  v_tally() function to tally the contribution.  Both the v_init() and
+  v_tally() methods are in the parent Fix class.  Note that there are
+  several variants of v_tally(); choose the one appropriate to your
+  fix.
+
+.. note::
+
+   The ev_init() and ev_tally() methods also account for global and
+   peratom virial contributions.  Thus you do not need to invoke the
+   v_init() and v_tally() methods, if the fix also calculates peratom
+   energies.
+
+The fix must also specify whether (by default) to include or exclude
+these contributions to the global/peratom energy/virial of the system.
+For the fix to include the contributions, set either of both of these
+variables in the constructor:
+
+* *thermo_energy* = 1, for global and peratom energy
+* *thermo_virial* = 1, for global and peratom virial
+
+Note that these variables are zeroed in fix.cpp.  Thus if you don't
+set the variables, the contributions will be excluded (by default)
+
+However, the user has ultimate control over whether to include or
+exclude the contributions of the fix via the :doc:`fix modify
+<fix_modify>` command:
+
+* fix modify *energy yes* to include global and peratom energy contributions
+* fix modify *virial yes* to include global and peratom virial contributions
+
+If the fix contributes to any of the global/peratom energy/virial
+values for the system, it should be explained on the fix doc page,
+along with the default values for the *energy yes/no* and *virial
+yes/no* settings of the :doc:`fix modify <fix_modify>` command.
+
+Finally, these 4 contributions are included in the output of 4
+computes:
+
+* global energy in :doc:`compute pe <compute_pe>`
+* peratom energy in :doc:`compute pe/atom <compute_pe_atom>`
+* global virial in :doc:`compute pressure <compute_pressure>`
+* peratom virial in :doc:`compute stress/atom <compute_stress_atom>`
+
+These computes invoke a method of the Modify class to include
+contributions from fixes that have the corresponding flags set,
+e.g. *energy_peratom_flag* and *thermo_energy* for :doc:`compute
+pe/atom <compute_pe_atom>`.
+
+Note that each compute has an optional keyword to either include or
+exclude all contributions from fixes.  Also note that :doc:`compute pe
+<compute_pe>` and :doc:`compute pressure <compute_pressure>` are what
+is used (by default) by :doc:`thermodynamic output <thermo_style>` to
+calculate values for its *pe* and *press* keywords.
+
+KSpace PPPM FFT grids
+^^^^^^^^^^^^^^^^^^^^^
+
+The various :doc:`KSpace PPPM <kspace_style>` styles in LAMMPS use
+FFTs to solve Poisson's equation.  This subsection describes:
+
+* how FFT grids are defined
+* how they are decomposed across processors
+* how they are indexed by each processor
+* how particle charge and electric field values are mapped to/from
+  the grid
+
+An FFT grid cell is a 3d volume; grid points are corners of a grid
+cell and the code stores values assigned to grid points in vectors or
+3d arrays.  A global 3d FFT grid has points indexed 0 to N-1 inclusive
+in each dimension.
+
+Each processor owns two subsets of the grid, each subset is
+brick-shaped.  Depending on how it is used, these subsets are
+allocated as a 1d vector or 3d array.  Either way, the ordering of
+values within contiguous memory x fastest, then y, z slowest.
+
+For the ``3d decomposition`` of the grid, the global grid is
+partitioned into bricks that correspond to the sub-domains of the
+simulation box that each processor owns.  Often, this is a regular 3d
+array (Px by Py by Pz) of bricks, where P = number of processors =
+Px * Py * Pz.  More generally it can be a tiled decomposition, where
+each processor owns a brick and the union of all the bricks is the
+global grid.  Tiled decompositions are produced by load balancing with
+the RCB algorithm; see the :doc:`balance rcb <balance>` command.
+
+For the ``FFT decompostion`` of the grid, each processor owns a brick
+that spans the entire x dimension of the grid while the y and z
+dimensions are partitioned as a regular 2d array (P1 by P2), where P =
+P1 * P2.
+
+The following indices store the inclusive bounds of the brick a
+processor owns, within the global grid:
+
+.. parsed-literal::
+
+   nxlo_in,nxhi_in,nylo_in,nyhi_in,nzlo_in,nzhi_in = 3d decomposition brick
+   nxlo_fft,nxhi_fft,nylo_fft,nyhi_fft,nzlo_fft,nzhi_fft = FFT decomposition brick
+   nxlo_out,nxhi_out,nylo_out,nyhi_out,nzlo_out,nzhi_out = 3d decomposition brick + ghost cells
+
+The ``in`` and ``fft`` indices are from 0 to N-1 inclusive in each
+dimension, where N is the grid size.
+
+The ``out`` indices index an array which stores the ``in`` subset of
+the grid plus ghost cells that surround it.  These indices can thus be
+< 0 or >= N.
+
+The number of ghost cells a processor owns in each of the 6 directions
+is a function of:
+
+.. parsed-literal::
+
+   neighbor skin distance (since atoms can move outside a proc subdomain)
+   qdist = offset or charge from atom due to TIP4P fictitious charge
+   order = mapping stencil size
+   shift = factor used when order is an even number (see below)
+
+Here is an explanation of how the PPPM variables ``order``,
+``nlower`` / ``nupper``, ``shift``, and ``OFFSET`` work. They are the
+relevant variables that determine how atom charge is mapped to grid
+points and how field values are mapped from grid points to atoms:
+
+.. parsed-literal::
+
+   order = # of nearby grid points in each dim that atom charge/field are mapped to/from
+   nlower,nupper = extent of stencil around the grid point an atom is assigned to
+   OFFSET = large integer added/subtracted when mapping to avoid int(-0.75) = 0 when -1 is the desired result
+
+The particle_map() method assigns each atom to a grid point.
+
+If order is even, say 4:
+
+.. parsed-literal::
+
+   atom is assigned to grid point to its left (in each dim)
+   shift = OFFSET
+   nlower = -1, nupper = 2, which are offsets from assigned grid point
+   window of mapping grid pts is thus 2 grid points to left of atom, 2 to right
+
+If order is odd, say 5:
+
+.. parsed-literal::
+
+   atom is assigned to left/right grid pt it is closest to (in each dim)
+   shift = OFFSET + 0.5
+   nlower = 2, nupper = 2
+   if point is in left half of cell, then window of affected grid pts is 3 grid points to left of atom, 2 to right
+   if point is in right half of cell, then window of affected grid pts is 2 grid points to left of atom, 3 to right
+
+These settings apply to each dimension, so that if order = 5, an
+atom's charge is mapped to 125 grid points that surround the atom.

doc/src/Developer_org.rst

@@ -1,68 +1,75 @@
 Source files
 ------------
 
-The source files of the LAMMPS code are found in two
-directories of the distribution: ``src`` and ``lib``.
-Most of the code is C++ but there are small numbers of files
-in several other languages.
+The source files of the LAMMPS code are found in two directories of the
+distribution: ``src`` and ``lib``.  Most of the code is written in C++
+but there are small a number of files in several other languages like C,
+Fortran, Shell script, or Python.
 
-The core of the code is located in the
-``src`` folder and its sub-directories.
-A sizable number of these files are in the ``src`` directory
-itself, but there are plenty of :doc:`packages <Packages>`, which can be
-included or excluded when LAMMPS is built.  See the :doc:`Include
-packages in build <Build_package>` section of the manual for more
-information about that part of the build process.  LAMMPS currently
-supports building with :doc:`conventional makefiles <Build_make>` and
-through :doc:`CMake <Build_cmake>` which differ in how packages are
-enabled or disabled for a LAMMPS binary.  The source files for each
+The core of the code is located in the ``src`` folder and its
+sub-directories.  A sizable number of these files are in the ``src``
+directory itself, but there are plenty of :doc:`packages <Packages>`,
+which can be included or excluded when LAMMPS is built.  See the
+:doc:`Include packages in build <Build_package>` section of the manual
+for more information about that part of the build process.  LAMMPS
+currently supports building with :doc:`conventional makefiles
+<Build_make>` and through :doc:`CMake <Build_cmake>`.  Those procedures
+differ in how packages are enabled or disabled for inclusion into a
+LAMMPS binary so they cannot be mixed.  The source files for each
 package are in all-uppercase sub-directories of the ``src`` folder, for
 example ``src/MOLECULE`` or ``src/USER-MISC``.  The ``src/STUBS``
 sub-directory is not a package but contains a dummy MPI library, that is
 used when building a serial version of the code. The ``src/MAKE``
-directory contains makefiles with settings and flags for a variety of
-configuration and machines for the build process with traditional
-makefiles.
+directory and its sub-directories contain makefiles with settings and
+flags for a variety of configuration and machines for the build process
+with traditional makefiles.
 
 The ``lib`` directory contains the source code for several supporting
 libraries or files with configuration settings to use globally installed
-libraries, that are required by some of the optional packages.
-Each sub-directory, like ``lib/poems`` or ``lib/gpu``, contains the
-source files, some of which are in different languages such as Fortran
-or CUDA. These libraries are linked to during a LAMMPS build, if the
-corresponding package is installed.
+libraries, that are required by some of the optional packages.  They may
+include python scripts that can transparently download additional source
+code on request.  Each sub-directory, like ``lib/poems`` or ``lib/gpu``,
+contains the source files, some of which are in different languages such
+as Fortran or CUDA. These libraries included in the LAMMPS build,
+if the corresponding package is installed.
 
 LAMMPS C++ source files almost always come in pairs, such as
 ``src/run.cpp`` (implementation file) and ``src/run.h`` (header file).
-Each pair of files defines a C++
-class, for example the :cpp:class:`LAMMPS_NS::Run` class which contains
-the code invoked by the :doc:`run <run>` command in a LAMMPS input script.
-As this example illustrates, source file and class names often have a
-one-to-one correspondence with a command used in a LAMMPS input script.
-Some source files and classes do not have a corresponding input script
+Each pair of files defines a C++ class, for example the
+:cpp:class:`LAMMPS_NS::Run` class which contains the code invoked by the
+:doc:`run <run>` command in a LAMMPS input script.  As this example
+illustrates, source file and class names often have a one-to-one
+correspondence with a command used in a LAMMPS input script.  Some
+source files and classes do not have a corresponding input script
 command, e.g. ``src/force.cpp`` and the :cpp:class:`LAMMPS_NS::Force`
 class.  They are discussed in the next section.
 
-A small number of C++ classes and utility functions are implemented with
-only a ``.h`` file. Examples are the Pointer class or the MathVec functions.
+The names of all source files are in lower case and may use the
+underscore character '_' to separate words. Outside of bundled libraries
+which may have different conventions, all C and C++ header files have a
+``.h`` extension, all C++ files have a ``.cpp`` extension, and C files a
+``.c`` extension. A small number of C++ classes and utility functions
+are implemented with only a ``.h`` file. Examples are the Pointer class
+or the MathVec functions.
 
 Class topology
 --------------
 
 Though LAMMPS has a lot of source files and classes, its class topology
-is relative flat, as outlined in the :ref:`class-topology` figure.  Each
-name refers to a class and has a pair of associated source files in the
-``src`` folder, for example the class :cpp:class:`LAMMPS_NS::Memory`
-corresponds to the files ``memory.cpp`` and ``memory.h``, or the class
-:cpp:class:`LAMMPS_NS::AtomVec` corresponds to the files
-``atom_vec.cpp`` and ``atom_vec.h``.  Full lines in the figure represent
-compositing: that is the class to the left holds a pointer to an
-instance of the class to the right.  Dashed lines instead represent
-inheritance: the class to the right is derived from the class on the
-left. Classes with a red boundary are not instantiated directly, but
-they represent the base classes for "styles".  Those "styles" make up
-the bulk of the LAMMPS code and only a few typical examples are included
-in the figure for demonstration purposes.
+is not very deep, which can be seen from the :ref:`class-topology`
+figure.  In that figure, each name refers to a class and has a pair of
+associated source files in the ``src`` folder, for example the class
+:cpp:class:`LAMMPS_NS::Memory` corresponds to the files ``memory.cpp``
+and ``memory.h``, or the class :cpp:class:`LAMMPS_NS::AtomVec`
+corresponds to the files ``atom_vec.cpp`` and ``atom_vec.h``.  Full
+lines in the figure represent compositing: that is the class at the base
+of the arrow holds a pointer to an instance of the class at the tip.
+Dashed lines instead represent inheritance: the class to the tip of the
+arrow is derived from the class at the base.  Classes with a red boundary
+are not instantiated directly, but they represent the base classes for
+"styles".  Those "styles" make up the bulk of the LAMMPS code and only
+a few representative examples are included in the figure so it remains
+readable.
 
 .. _class-topology:
 .. figure:: JPG/lammps-classes.png
@@ -82,69 +89,76 @@ in the figure for demonstration purposes.
    derived classes, which may also hold instances of other classes.
 
 The :cpp:class:`LAMMPS_NS::LAMMPS` class is the topmost class and
-represents what is referred to an "instance" of LAMMPS.  It is a
-composite holding references to instances of other core classes
+represents what is generally referred to an "instance" of LAMMPS.  It is
+a composite holding pointers to instances of other core classes
 providing the core functionality of the MD engine in LAMMPS and through
 them abstractions of the required operations.  The constructor of the
 LAMMPS class will instantiate those instances, process the command line
 flags, initialize MPI (if not already done) and set up file pointers for
-input and output. The destructor will shut everything down and free all
+input and output.  The destructor will shut everything down and free all
 associated memory.  Thus code for the standalone LAMMPS executable in
 ``main.cpp`` simply initializes MPI, instantiates a single instance of
-LAMMPS, and passes it the command line flags and input script. It
+LAMMPS while passing it the command line flags and input script. It
 deletes the LAMMPS instance after the method reading the input returns
 and shuts down the MPI environment before it exits the executable.
 
 The :cpp:class:`LAMMPS_NS::Pointers` is not shown in the
-:ref:`class-topology` figure, it holds references to members of the
-`LAMMPS_NS::LAMMPS`, so that all classes derived from
-:cpp:class:`LAMMPS_NS::Pointers` have direct access to those reference.
-From the class topology all classes with blue boundary are referenced in
-this class and all classes in the second and third columns, that are not
-listed as derived classes are instead derived from
-:cpp:class:`LAMMPS_NS::Pointers`.
+:ref:`class-topology` figure for clarity.  It holds references to many
+of the members of the `LAMMPS_NS::LAMMPS`, so that all classes derived
+from :cpp:class:`LAMMPS_NS::Pointers` have direct access to those
+reference.  From the class topology all classes with blue boundary are
+referenced in the Pointers class and all classes in the second and third
+columns, that are not listed as derived classes are instead derived from
+:cpp:class:`LAMMPS_NS::Pointers`.  To initialize the pointer references
+in Pointers, a pointer to the LAMMPS class instance needs to be passed
+to the constructor and thus all constructors for classes derived from it
+must do so and pass this pointer to the constructor for Pointers.
 
-Since all storage is encapsulated, the LAMMPS class can also be
-instantiated multiple times by a calling code, and that can be either
-simultaneously or consecutively.  When running in parallel with MPI,
-care has to be taken, that suitable communicators are used to not
-create conflicts between different instances.
+Since all storage is supposed to be encapsulated (there are a few
+exceptions), the LAMMPS class can also be instantiated multiple times by
+a calling code.  Outside of the aforementioned exceptions, those LAMMPS
+instances can be used alternately.  As of the time of this writing
+(early 2021) LAMMPS is not yet sufficiently thread-safe for concurrent
+execution.  When running in parallel with MPI, care has to be taken,
+that suitable copies of communicators are used to not create conflicts
+between different instances.
 
-The LAMMPS class currently holds instances of 19 classes representing
-different core functionalities There are a handful of virtual parent
-classes in LAMMPS that define what LAMMPS calls ``styles``.  They are
-shaded red in the :ref:`class-topology` figure.  Each of these are
+The LAMMPS class currently (early 2021) holds instances of 19 classes
+representing the core functionality.  There are a handful of virtual
+parent classes in LAMMPS that define what LAMMPS calls ``styles``.  They
+are shaded red in the :ref:`class-topology` figure.  Each of these are
 parents of a number of child classes that implement the interface
 defined by the parent class.  There are two main categories of these
 ``styles``: some may only have one instance active at a time (e.g. atom,
 pair, bond, angle, dihedral, improper, kspace, comm) and there is a
-dedicated pointer variable in the composite class that manages them.
+dedicated pointer variable for each of them in the composite class.
 Setups that require a mix of different such styles have to use a
-*hybrid* class that manages and forwards calls to the corresponding
-sub-styles for the designated subset of atoms or data. or the composite
-class may have lists of class instances, e.g. Modify handles lists of
-compute and fix styles, while Output handles dumps class instances.
+*hybrid* class that takes the place of the one allowed instance and then
+manages and forwards calls to the corresponding sub-styles for the
+designated subset of atoms or data.  The composite class may also have
+lists of class instances, e.g. Modify handles lists of compute and fix
+styles, while Output handles a list of dump class instances.
 
-The exception to this scheme are the ``command`` style classes. These
-implement specific commands that can be invoked before, after, or between
-runs or are commands which launch a simulation.  For these an instance
-of the class is created, its command() method called and then, after
-completion, the class instance deleted.  Examples for this are the
-create_box, create_atoms, minimize, run, or velocity command styles.
+The exception to this scheme are the ``command`` style classes.  These
+implement specific commands that can be invoked before, after, or in
+between runs.  For these an instance of the class is created, its
+command() method called and then, after completion, the class instance
+deleted.  Examples for this are the create_box, create_atoms, minimize,
+run, or velocity command styles.
 
 For all those ``styles`` certain naming conventions are employed: for
-the fix nve command the class is called FixNVE and the files are
+the fix nve command the class is called FixNVE and the source files are
 ``fix_nve.h`` and ``fix_nve.cpp``. Similarly for fix ave/time we have
-FixAveTime and ``fix_ave_time.h`` and ``fix_ave_time.cpp``. Style names
+FixAveTime and ``fix_ave_time.h`` and ``fix_ave_time.cpp``.  Style names
 are lower case and without spaces or special characters. A suffix or
-multiple appended with a forward slash '/' denotes a variant of the
-corresponding class without the suffix. To connect the style name and
-the class name, LAMMPS uses macros like the following ATOM\_CLASS,
-PAIR\_CLASS, BOND\_CLASS, REGION\_CLASS, FIX\_CLASS, COMPUTE\_CLASS,
-or DUMP\_CLASS in the corresponding header file.  During compilation
-files with the pattern ``style_name.h`` are created that contain include
-statements including all headers of all styles of a given type that
-are currently active (or "installed).
+words are appended with a forward slash '/' which denotes a variant of
+the corresponding class without the suffix.  To connect the style name
+and the class name, LAMMPS uses macros like: ``AtomStyle()``,
+``PairStyle()``, ``BondStyle()``, ``RegionStyle()``, and so on in the
+corresponding header file.  During configuration or compilation files
+with the pattern ``style_<name>.h`` are created that consist of a list
+of include statements including all headers of all styles of a given
+type that are currently active (or "installed).
 
 
 More details on individual classes in the :ref:`class-topology` are as
@@ -152,11 +166,11 @@ follows:
 
 - The Memory class handles allocation of all large vectors and arrays.
 
-- The Error class prints all error and warning messages.
+- The Error class prints all (terminal) error and warning messages.
 
-- The Universe class sets up partitions of processors so that multiple
-  simulations can be run, each on a subset of the processors allocated
-  for a run, e.g. by the mpirun command.
+- The Universe class sets up one or more partitions of processors so
+  that one or multiple simulations can be run, on the processors
+  allocated for a run, e.g. by the mpirun command.
 
 - The Input class reads and processes input input strings and files,
   stores variables, and invokes :doc:`commands <Commands_all>`.
@@ -241,7 +255,8 @@ follows:
 .. 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
+..       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

doc/src/Developer_unittest.rst

@@ -0,0 +1,523 @@
+Adding tests for unit testing
+-----------------------------
+
+This section discusses adding or expanding tests for the unit test
+infrastructure included into the LAMMPS source code distribution.
+Unlike example inputs, unit tests focus on testing the "local" behavior
+of individual features, tend to run very fast, and should be set up to
+cover as much of the added code as possible.  When contributing code to
+the distribution, the LAMMPS developers will appreciate if additions
+to the integrated unit test facility are included.
+
+Given the complex nature of MD simulations where many operations can
+only be performed when suitable "real" simulation environment has been
+set up, not all tests will be unit tests in the strict definition of
+the term.  They are rather executed on a more abstract level by issuing
+LAMMPS script commands and then inspecting the changes to the internal
+data.  For some classes of tests, generic test programs have been
+written that can be applied to parts of LAMMPS that use the same
+interface (via polymorphism) and those are driven by input files, so
+tests can be added by simply adding more of those input files.  Those
+tests should be seen more as a hybrid between unit and regression tests.
+
+When adding tests it is recommended to also :ref:`enable support for
+code coverage reporting <testing>`, and study the coverage reports
+so that it is possible to monitor which parts of the code of a given
+file are executed during the tests and which tests would need to be
+added to increase the coverage.
+
+The tests are grouped into categories and corresponding folders.
+The following sections describe how the tests are implemented and
+executed in those categories with increasing complexity of tests
+and implementation.
+
+
+Tests for utility functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These tests are driven by programs in the ``unittest/utils`` folder
+and most closely resemble conventional unit tests. There is one test
+program for each namespace or group of classes or file. The naming
+convention for the sources and executables is that they start with
+with ``test_``.  The following sources and groups of tests are currently
+available:
+
+.. list-table::
+   :header-rows: 1
+   :widths: auto
+   :align: left
+
+   * - File name:
+     - Test name:
+     - Description:
+   * - ``test_fmtlib.cpp``
+     - FmtLib
+     - Tests for ``fmtlib::`` functions used by LAMMPS
+   * - ``test_math_eigen_impl.cpp``
+     - MathEigen
+     - Tests for ``MathEigen::`` classes and functions
+   * - ``test_mempool.cpp``
+     - MemPool
+     - Tests for :cpp:class:`MyPage <LAMMPS_NS::MyPage>` and :cpp:class:`MyPoolChunk <LAMMPS_NS::MyPoolChunk>`
+   * - ``test_tokenizer.cpp``
+     - Tokenizer
+     - Tests for :cpp:class:`Tokenizer <LAMMPS_NS::Tokenizer>` and :cpp:class:`ValueTokenizer <LAMMPS_NS::ValueTokenizer>`
+   * - ``test_utils.cpp``
+     - Utils
+     - Tests for ``utils::`` :doc:`functions <Developer_utils>`
+
+To add tests either an existing source file needs to be modified or a
+new source file needs to be added to the distribution and enabled for
+testing.  To add a new file suitable CMake script code needs to be added
+to the ``CMakeLists.txt`` file in the ``unittest/utils`` folder.  Example:
+
+.. code-block:: cmake
+
+   add_executable(test_tokenizer test_tokenizer.cpp)
+   target_link_libraries(test_tokenizer PRIVATE lammps GTest::GMockMain GTest::GMock GTest::GTest)
+   add_test(Tokenizer test_tokenizer)
+
+This adds instructions to build the ``test_tokenizer`` executable from
+``test_tokenizer.cpp`` and links it with the GoogleTest libraries and the
+LAMMPS library as well as it uses the ``main()`` function from the
+GoogleMock library of GoogleTest.  The third line registers the executable
+as a test program to be run from ``ctest`` under the name ``Tokenizer``.
+
+The test executable itself will execute multiple individual tests
+through the GoogleTest framework. In this case each test consists of
+creating a tokenizer class instance with a given string and explicit or
+default separator choice, and then executing member functions of the
+class and comparing their results with expected values. A few examples:
+
+.. code-block:: c++
+
+   TEST(Tokenizer, empty_string)
+   {
+       Tokenizer t("", " ");
+       ASSERT_EQ(t.count(), 0);
+   }
+
+   TEST(Tokenizer, two_words)
+   {
+       Tokenizer t("test word", " ");
+       ASSERT_EQ(t.count(), 2);
+   }
+
+   TEST(Tokenizer, default_separators)
+   {
+       Tokenizer t(" \r\n test \t word \f");
+       ASSERT_THAT(t.next(), Eq("test"));
+       ASSERT_THAT(t.next(), Eq("word"));
+       ASSERT_EQ(t.count(), 2);
+   }
+
+Each of these TEST functions will become an individual
+test run by the test program. When using the ``ctest``
+command as a front end to run the tests, their output
+will be suppressed and only a summary printed, but adding
+the '-V' option will then produce output from the tests
+above like the following:
+
+.. code-block::
+
+   [...]
+   1: [ RUN      ] Tokenizer.empty_string
+   1: [       OK ] Tokenizer.empty_string (0 ms)
+   1: [ RUN      ] Tokenizer.two_words
+   1: [       OK ] Tokenizer.two_words (0 ms)
+   1: [ RUN      ] Tokenizer.default_separators
+   1: [       OK ] Tokenizer.default_separators (0 ms)
+   [...]
+
+The MathEigen test collection has been adapted from a standalone test
+and does not use the GoogleTest framework and thus not representative.
+The other test sources, however, can serve as guiding examples for
+additional tests.
+
+Tests for individual LAMMPS commands
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The tests ``unittest/commands`` are a bit more complex as they require
+to first create a :cpp:class:`LAMMPS <LAMMPS_NS::LAMMPS>` class instance
+and then use the :doc:`C++ API <Cplusplus>` to pass individual commands
+to that LAMMPS instance.  For that reason these tests use a GoogleTest
+"test fixture", i.e. a class derived from ``testing::Test`` that will
+create (and delete) the required LAMMPS class instance for each set of
+tests in a ``TEST_F()`` function.  Please see the individual source files
+for different examples of setting up suitable test fixtures.  Here is an
+example for implementing a test using a fixture by first checking the
+default value and then issuing LAMMPS commands and checking whether they
+have the desired effect:
+
+.. code-block:: c++
+
+   TEST_F(SimpleCommandsTest, ResetTimestep)
+   {
+       ASSERT_EQ(lmp->update->ntimestep, 0);
+
+       if (!verbose) ::testing::internal::CaptureStdout();
+       lmp->input->one("reset_timestep 10");
+       if (!verbose) ::testing::internal::GetCapturedStdout();
+       ASSERT_EQ(lmp->update->ntimestep, 10);
+
+       if (!verbose) ::testing::internal::CaptureStdout();
+       lmp->input->one("reset_timestep 0");
+       if (!verbose) ::testing::internal::GetCapturedStdout();
+       ASSERT_EQ(lmp->update->ntimestep, 0);
+   }
+
+Please note the use of the (global) verbose variable to control whether
+the LAMMPS command will be silent by capturing the output or not.  In
+the default case, verbose == false, the test output will be compact and
+not mixed with LAMMPS output. However setting the verbose flag (via
+setting the ``TEST_ARGS`` environment variable, ``TEST_ARGS=-v``) can be
+helpful to understand why tests fail unexpectedly.
+
+Another complexity of these tests stems from the need to capture
+situations where LAMMPS will stop with an error, i.e. handle so-called
+"death tests".  Here the LAMMPS code will operate differently depending
+on whether it was configured to throw C++ exceptions on errors or call
+either ``exit()`` or ``MPI_Abort()``.  In the latter case, the test code
+also needs to detect whether LAMMPS was compiled with the OpenMPI
+library, as OpenMPI is **only** compatible the death test options of the
+GoogleTest library when C++ exceptions are enabled; otherwise those
+"death tests" must be skipped to avoid reporting bogus failures.  The
+specifics of this step are implemented in the ``TEST_FAILURE()``
+macro. These tests operate by capturing the screen output when executing
+the failing command and then comparing that with a provided regular
+expression string pattern.  Example:
+
+.. code-block:: C++
+
+   TEST_F(SimpleCommandsTest, UnknownCommand)
+   {
+       TEST_FAILURE(".*ERROR: Unknown command.*", lmp->input->one("XXX one two"););
+   }
+
+The following test programs are currently available:
+
+.. list-table::
+   :header-rows: 1
+   :widths: auto
+   :align: left
+
+   * - File name:
+     - Test name:
+     - Description:
+   * - ``test_simple_commands.cpp``
+     - SimpleCommands
+     - Tests for LAMMPS commands that do not require a box
+   * - ``test_lattice_region.cpp``
+     - LatticeRegion
+     - Tests to validate the :doc:`lattice <lattice>` and :doc:`region <region>` commands
+   * - ``test_kim_commands.cpp``
+     - KimCommands
+     - Tests for several commands from the :ref:`KIM package <PKG-KIM>`
+   * - ``test_reset_ids.cpp``
+     - ResetIDs
+     - Tests to validate the :doc:`reset_atom_ids <reset_atom_ids>` and :doc:`reset_mol_ids <reset_mol_ids>` commands
+
+
+Tests for the C-style library interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Tests for validating the LAMMPS C-style library interface are in the
+``unittest/c-library`` folder.  They are implemented in either way used
+for utility functions and for LAMMPS commands, but use the functions
+implemented in the ``src/library.cpp`` file as much as possible.  There
+may be some overlap with other tests, but only in as much as is required
+to test the C-style library API.  The tests are distributed over
+multiple test programs which tries to match the grouping of the
+functions in the source code and :ref:`in the manual <lammps_c_api>`.
+
+This group of tests also includes tests invoking LAMMPS in parallel
+through the library interface, provided that LAMMPS was compiled with
+MPI support.  These include tests where LAMMPS is run in multi-partition
+mode or only on a subset of the MPI world communicator.  The CMake
+script code for adding this kind of test looks like this:
+
+.. code-block:: CMake
+
+   if (BUILD_MPI)
+     add_executable(test_library_mpi test_library_mpi.cpp)
+     target_link_libraries(test_library_mpi PRIVATE lammps GTest::GTest GTest::GMock)
+     target_compile_definitions(test_library_mpi PRIVATE ${TEST_CONFIG_DEFS})
+     add_mpi_test(NAME LibraryMPI NUM_PROCS 4 COMMAND $<TARGET_FILE:test_library_mpi>)
+   endif()
+
+Note the custom function ``add_mpi_test()`` which adapts how ``ctest``
+will execute the test so it is launched in parallel (with 4 MPI ranks).
+
+Tests for the Python module and package
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``unittest/python`` folder contains primarily tests for classes and
+functions in the LAMMPS python module but also for commands in the
+PYTHON package.  These tests are only enabled, if the necessary
+prerequisites are detected or enabled during configuration and
+compilation of LAMMPS (shared library build enabled, Python interpreter
+found, Python development files found).
+
+The Python tests are implemented using the ``unittest`` standard Python
+module and split into multiple files with similar categories as the
+tests for the C-style library interface.
+
+Tests for the Fortran interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Tests for using the Fortran module are in the ``unittest/fortran``
+folder.  Since they are also using the GoogleTest library, they require
+to also implement test wrappers in C++ that will call fortran functions
+which provide a C function interface through ISO_C_BINDINGS that will in
+turn call the functions in the LAMMPS Fortran module.  This part of the
+unit tests is incomplete since the Fortran module it is based on is
+incomplete as well.
+
+Tests for the C++-style library interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The tests in the ``unittest/cplusplus`` folder are somewhat similar to
+the tests for the C-style library interface, but do not need to test the
+several convenience and utility functions that are only available through
+the C-style interface.  Instead it can focus on the more generic features
+that are used internally.  This part of the unit tests is currently still
+mostly in the planning stage.
+
+Tests for reading and writing file formats
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``unittest/formats`` folder contains test programs for reading and
+writing files like data files, restart files, potential files or dump files.
+This covers simple things like the file i/o convenience functions in the
+``utils::`` namespace to complex tests of atom styles where creating and
+deleting of atoms with different properties is tested in different ways
+and through script commands or reading and writing of data or restart files.
+
+Tests for styles computing or modifying forces
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These are tests common configurations for pair styles, bond styles,
+angle styles, kspace styles and certain fix styles.  Those are tests
+driven by some test executables build from sources in the
+``unittest/force-styles`` folder and use LAMMPS input template and data
+files as well as input files in YAML format from the
+``unittest/force-styles/tests`` folder. The YAML file names have to
+follow some naming conventions so they get associated with the test
+programs and categorized and listed with canonical names in the list
+of tests as displayed by ``ctest -N``.  If you add a new YAML file,
+you need to re-run CMake to update the corresponding list of tests.
+
+A minimal YAML file for a (molecular) pair style test will looks
+something like the following (see ``mol-pair-zero.yaml``):
+
+.. code-block:: yaml
+
+   ---
+   lammps_version: 24 Aug 2020
+   date_generated: Tue Sep 15 09:44:21 202
+   epsilon: 1e-14
+   prerequisites: ! |
+     atom full
+     pair zero
+   pre_commands: ! ""
+   post_commands: ! ""
+   input_file: in.fourmol
+   pair_style: zero 8.0
+   pair_coeff: ! |
+     * *
+   extract: ! ""
+   natoms: 29
+   init_vdwl: 0
+   init_coul: 0
+
+   [...]
+
+The following table describes the available keys and their purpose for
+testing pair styles:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Key:
+     - Description:
+   * - lammps_version
+     - LAMMPS version used to last update the reference data
+   * - date_generated
+     - date when the file was last updated
+   * - epsilon
+     - base value for the relative precision required for tests to pass
+   * - prerequisites
+     - list of style kind / style name pairs required to run the test
+   * - pre_commands
+     - LAMMPS commands to be executed before the input template file is read
+   * - post_commands
+     - LAMMPS commands to be executed right before the actual tests
+   * - input_file
+     - LAMMPS input file template based on pair style zero
+   * - pair_style
+     - arguments to the pair_style command to be tested
+   * - pair_coeff
+     - list of pair_coeff arguments to set parameters for the input template
+   * - extract
+     - list of keywords supported by ``Pair::extract()`` and their dimension
+   * - natoms
+     - number of atoms in the input file template
+   * - init_vdwl
+     - non-Coulomb pair energy after "run 0"
+   * - init_coul
+     - Coulomb pair energy after "run 0"
+   * - init_stress
+     - stress tensor after "run 0"
+   * - init_forces
+     - forces on atoms after "run 0"
+   * - run_vdwl
+     - non-Coulomb pair energy after "run 4"
+   * - run_coul
+     - Coulomb pair energy after "run 4"
+   * - run_stress
+     - stress tensor after "run 4"
+   * - run_forces
+     - forces on atoms after "run 4"
+
+The test program will read all this data from the YAML file and then
+create a LAMMPS instance, apply the settings/commands from the YAML file
+as needed and then issue a "run 0" command, write out a restart file, a
+data file and a coeff file. The actual test will then compare computed
+energies, stresses, and forces with the reference data, issue a "run 4"
+command and compare to the second set of reference data.  This will be
+run with both the newton_pair setting enabled and disabled and is
+expected to generate the same results (allowing for some numerical
+noise). Then it will restart from the previously generated restart and
+compare with the reference and also start from the data file.  A final
+check will use multi-cutoff r-RESPA (if supported by the pair style) at
+a 1:1 split and compare to the Verlet results.  These sets of tests are
+run with multiple test fixtures for accelerated styles (OPT, USER-OMP,
+USER-INTEL) and for the latter two with 4 OpenMP threads enabled.  For
+these tests the relative error (epsilon) is lowered by a common factor
+due to the additional numerical noise, but the tests are still comparing
+to the same reference data.
+
+Additional tests will check whether all listed extract keywords are
+supported and have the correct dimensionality and the final set of tests
+will set up a few pairs of atoms explicitly and in such a fashion that
+the forces on the atoms computed from ``Pair::compute()`` will match
+individually with the results from ``Pair::single()``, if the pair style
+does support that functionality.
+
+With this scheme a large fraction of the code of any tested pair style
+will be executed and consistent results are required for different
+settings and between different accelerated pair style variants and the
+base class, as well as for computing individual pairs through the
+``Pair::single()`` where supported.
+
+The ``test_pair_style`` tester is used with 4 categories of test inputs:
+
+- pair styles compatible with molecular systems using bonded
+  interactions and exclusions.  For pair styles requiring a KSpace style
+  the KSpace computations are disabled.  The YAML files match the
+  pattern "mol-pair-\*.yaml" and the tests are correspondingly labeled
+  with "MolPairStyle:\*"
+- pair styles not compatible with the previous input template.
+  The YAML files match the pattern "atomic-pair-\*.yaml" and the tests are
+  correspondingly labeled with "AtomicPairStyle:\*"
+- manybody pair styles.
+  The YAML files match the pattern "atomic-pair-\*.yaml" and the tests are
+  correspondingly labeled with "AtomicPairStyle:\*"
+- kspace styles.
+  The YAML files match the pattern "kspace-\*.yaml" and the tests are
+  correspondingly labeled with "KSpaceStyle:\*". In these cases a compatible
+  pair style is defined, but the computation of the pair style contributions
+  is disabled.
+
+The ``test_bond_style`` and ``test_angle_style`` are set up in a similar
+fashion and share support functions with the pair style tester.  The final
+group of tests in this section is for fix styles that add/manipulate forces
+and velocities, e.g. for time integration, thermostats and more.
+
+Adding a new test is easiest done by copying and modifying an existing test
+for a style that is similar to one to be tested.  The file name should follow
+the naming conventions described above and after copying the file, the first
+step is to replace the style names where needed.  The coefficient values
+do not have to be meaningful, just in a reasonable range for the given system.
+It does not matter if some forces are large, for as long as they do not diverge.
+
+The template input files define a large number of index variables at the top
+that can be modified inside the YAML file to control the behavior.  For example,
+if a pair style requires a "newton on" setting, the following can be used in
+as the "pre_commands" section:
+
+.. code-block:: yaml
+
+   pre_commands: ! |
+     variable newton_pair delete
+     variable newton_pair index on
+
+And for a pair style requiring a kspace solver the following would be used as
+the "post_commands" section:
+
+.. code-block:: yaml
+
+   post_commands: ! |
+     pair_modify table 0
+     kspace_style pppm/tip4p 1.0e-6
+     kspace_modify gewald 0.3
+     kspace_modify compute no
+
+Note that this disables computing the kspace contribution, but still will run
+the setup.  The "gewald" parameter should be set explicitly to speed up the run.
+For styles with long-range electrostatics, typically two tests are added one using
+the (slower) analytic approximation of the erfc() function and the other using
+the tabulated coulomb, to test both code paths. The reference results in the YAML
+files then should be compared manually, if they agree well enough within the limits
+of those two approximations.
+
+The ``test_pair_style`` and equivalent programs have special command line options
+to update the YAML files. Running a command like
+
+.. code-block:: bash
+
+   $ test_pair_style mol-pair-lennard_mdf.yaml -g new.yaml
+
+will read the settings from the ``mol-pair-lennard_mdf.yaml`` file and then compute
+the reference data and write a new file with to ``new.yaml``.  If this step fails,
+there are likely some (LAMMPS or YAML) syntax issues in the YAML file that need to
+be resolved and then one can compare the two files to see if the output is as expected.
+
+It is also possible to do an update in place with:
+
+.. code-block:: bash
+
+   $ test_pair_style mol-pair-lennard_mdf.yaml -u
+
+And one can finally run the full set of tests with:
+
+.. code-block:: bash
+
+   $ test_pair_style mol-pair-lennard_mdf.yaml
+
+This will just print a summary of the groups of tests.  When using the "-v" flag
+the test will also keep any LAMMPS output and when using the "-s" flag, there
+will be some statistics reported on the relative errors for the individual checks
+which can help to figure out what would be a good choice of the epsilon parameter.
+It should be as small as possible to catch any unintended side effects from changes
+elsewhere, but large enough to accommodate the numerical noise due to the implementation
+of the potentials and differences in compilers.
+
+.. note::
+
+   These kinds of tests can be very sensitive to compiler optimization and
+   thus the expectation is that they pass with compiler optimization turned
+   off. When compiler optimization is enabled, there may be some failures, but
+   one has to carefully check whether those are acceptable due to the enhanced
+   numerical noise from reordering floating-point math operations or due to
+   the compiler mis-compiling the code. That is not always obvious.
+
+
+Tests for programs in the tools folder
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``unittest/tools`` folder contains tests for programs in the
+``tools`` folder.  This currently only contains tests for the LAMMPS
+shell, which are implemented as a python scripts using the ``unittest``
+Python module and launching the tool commands through the ``subprocess``
+Python module.

doc/src/Developer_utils.rst

@@ -71,12 +71,21 @@ and parsing files or arguments.
 
 ----------
 
+.. doxygenfunction:: strdup
+   :project: progguide
+
 .. doxygenfunction:: trim
    :project: progguide
 
 .. doxygenfunction:: trim_comment
    :project: progguide
 
+.. doxygenfunction:: has_utf8
+   :project: progguide
+
+.. doxygenfunction:: utf8_subst
+   :project: progguide
+
 .. doxygenfunction:: count_words(const char *text)
    :project: progguide
 
@@ -95,6 +104,9 @@ and parsing files or arguments.
 .. doxygenfunction:: strmatch
    :project: progguide
 
+.. doxygenfunction:: strfind
+   :project: progguide
+
 .. doxygenfunction:: is_integer
    :project: progguide
 
@@ -286,6 +298,50 @@ This code example should produce the following output:
 
 ----------
 
+
+Argument parsing classes
+---------------------------
+
+The purpose of argument parsing classes it to simplify and unify how
+arguments of commands in LAMMPS are parsed and to make abstractions of
+repetitive tasks.
+
+The :cpp:class:`LAMMPS_NS::ArgInfo` class provides an abstraction
+for parsing references to compute or fix styles or variables. These
+would start with a "c\_", "f\_", "v\_" followed by the ID or name of
+than instance and may be postfixed with one or two array indices
+"[<number>]" with numbers > 0.
+
+A typical code segment would look like this:
+
+.. code-block:: C++
+   :caption: Usage example for ArgInfo class
+
+   int nvalues = 0;
+   for (iarg = 0; iarg < nargnew; iarg++) {
+     ArgInfo argi(arg[iarg]);
+
+     which[nvalues] = argi.get_type();
+     argindex[nvalues] = argi.get_index1();
+     ids[nvalues] = argi.copy_name();
+
+     if ((which[nvalues] == ArgInfo::UNKNOWN)
+          || (which[nvalues] == ArgInfo::NONE)
+          || (argi.get_dim() > 1))
+       error->all(FLERR,"Illegal compute XXX command");
+
+     nvalues++;
+   }
+
+----------
+
+.. doxygenclass:: LAMMPS_NS::ArgInfo
+   :project: progguide
+   :members:
+
+
+----------
+
 File reader classes
 -------------------
 

doc/src/Errors_warnings.rst

@@ -119,7 +119,6 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
    :doc:`pair style zero <pair_zero>` with a suitable cutoff or use :doc:`comm_modify cutoff <comm_modify>`.
 
 *Communication cutoff is shorter than a bond length based estimate. This may lead to errors.*
-
    Since LAMMPS stores topology data with individual atoms, all atoms
    comprising a bond, angle, dihedral or improper must be present on any
    sub-domain that "owns" the atom with the information, either as a

doc/src/Howto_cmake.rst

@@ -296,6 +296,8 @@ Some common CMake variables
      - Description
    * - ``CMAKE_INSTALL_PREFIX``
      - root directory of install location for ``make install``  (default: ``$HOME/.local``)
+   * - ``LAMMPS_INSTALL_RPATH``
+     - set or remove runtime path setting from binaries for ``make install`` (default: ``off``)
    * - ``CMAKE_BUILD_TYPE``
      - controls compilation options:
        one of ``RelWithDebInfo`` (default), ``Release``, ``Debug``, ``MinSizeRel``

doc/src/Howto_drude.rst

@@ -42,10 +42,11 @@ screening. It may be necessary to use the *extra/special/per/atom*
 keyword of the :doc:`read_data <read_data>` command. If using :doc:`fix shake <fix_shake>`, make sure no Drude particle is in this fix
 group.
 
-There are two ways to thermostat the Drude particles at a low
+There are three ways to thermostat the Drude particles at a low
 temperature: use either :doc:`fix langevin/drude <fix_langevin_drude>`
 for a Langevin thermostat, or :doc:`fix drude/transform/\* <fix_drude_transform>` for a Nose-Hoover
-thermostat. The former requires use of the command :doc:`comm_modify vel yes <comm_modify>`. The latter requires two separate integration
+thermostat, or :doc:`fix tgnvt/drude <fix_tgnh_drude>` for a temperature-grouped Nose-Hoover thermostat.
+The first and third require use of the command :doc:`comm_modify vel yes <comm_modify>`. The second requires two separate integration
 fixes like *nvt* or *npt*\ . The correct temperatures of the reduced
 degrees of freedom can be calculated using the :doc:`compute temp/drude <compute_temp_drude>`. This requires also to use the
 command *comm_modify vel yes*.

doc/src/Howto_drude2.rst

@@ -36,7 +36,7 @@ polarizability :math:`\alpha` by
 
 Ideally, the mass of the Drude particle should be small, and the
 stiffness of the harmonic bond should be large, so that the Drude
-particle remains close ot the core. The values of Drude mass, Drude
+particle remains close to the core. The values of Drude mass, Drude
 charge, and force constant can be chosen following different
 strategies, as in the following examples of polarizable force
 fields:
@@ -221,6 +221,14 @@ modification of forces but no position/velocity updates), the fix
 
    fix NVE all nve
 
+To avoid the flying ice cube artifact, where the atoms progressively freeze and the
+center of mass of the whole system drifts faster and faster, the *fix momentum*
+can be used. For instance:
+
+.. code-block:: LAMMPS
+
+   fix MOMENTUM all momentum 100 linear 1 1 1
+
 Finally, do not forget to update the atom type elements if you use
 them in a *dump_modify ... element ...* command, by adding the element
 type of the DPs. Here for instance
@@ -376,14 +384,7 @@ For our phenol example, the groups would be defined as
 
 Note that with the fixes *drude/transform*\ , it is not required to
 specify *comm_modify vel yes* because the fixes do it anyway (several
-times and for the forces also).  To avoid the flying ice cube artifact
-:ref:`(Lamoureux and Roux) <Lamoureux2>`, where the atoms progressively freeze and the
-center of mass of the whole system drifts faster and faster, the *fix
-momentum* can be used. For instance:
-
-.. code-block:: LAMMPS
-
-   fix MOMENTUM all momentum 100 linear 1 1 1
+times and for the forces also).
 
 It is a bit more tricky to run a NPT simulation with Nose-Hoover
 barostat and thermostat.  First, the volume should be integrated only
@@ -404,6 +405,31 @@ instructions for thermostatting and barostatting will look like
    fix NVT DRUDES nvt temp 1. 1. 20
    fix INVERSE all drude/transform/inverse
 
+Another option for thermalizing the Drude model is to use the
+temperature-grouped Nose-Hoover (TGNH) thermostat proposed by :ref:`(Son) <TGNH-SON>`.
+This is implemented as :doc:`fix tgnvt/drude <fix_tgnh_drude>` and :doc:`fix tgnpt/drude <fix_tgnh_drude>`.
+It separates the kinetic energy into three contributions:
+the molecular center of mass (COM) motion, the motion of atoms or atom-Drude pairs relative to molecular COMs,
+and the relative motion of atom-Drude pairs.
+An independent Nose-Hoover chain is applied to each type of motion.
+When TGNH is used, the temperatures of molecular, atomic and Drude motion can be printed out with :doc:`thermo_style` command.
+
+NVT simulation with TGNH thermostat
+
+.. code-block:: LAMMPS
+
+   comm_modify vel yes
+   fix TGNVT all tgnvt/drude temp 300. 300. 100 1. 20
+   thermo_style custom f_TGNVT[1] f_TGNVT[2] f_TGNVT[3]
+
+NPT simulation with TGNH thermostat
+
+.. code-block:: LAMMPS
+
+   comm_modify vel yes
+   fix TGNPT all tgnpt/drude temp 300. 300. 100 1. 20 iso 1. 1. 500
+   thermo_style custom f_TGNPT[1] f_TGNPT[2] f_TGNPT[3]
+
 ----------
 
 **Rigid bodies**
@@ -480,3 +506,7 @@ NPT ensemble using Nose-Hoover thermostat:
 
 **(SWM4-NDP)** Lamoureux, Harder, Vorobyov, Roux, MacKerell, Chem Phys
 Let, 418, 245-249 (2006)
+
+.. _TGNH-Son:
+
+**(Son)** Son, McDaniel, Cui and Yethiraj, J Phys Chem Lett, 10, 7523 (2019).

doc/src/Howto_github.rst

@@ -72,7 +72,7 @@ explained in more detail here: `feature branch workflow <https://www.atlassian.c
 
 **Feature branches**
 
-First of all, create a clone of your version on github on your local
+First of all, create a clone of your version on GitHub on your local
 machine via HTTPS:
 
 .. code-block:: bash
@@ -155,7 +155,7 @@ useful message that explains the change.
 
 .. code-block:: bash
 
-     $ git commit -m 'Finally updated the github tutorial'
+     $ git commit -m 'Finally updated the GitHub tutorial'
 
 After the commit, the changes can be pushed to the same branch on GitHub:
 

doc/src/Howto_pylammps.rst

@@ -9,8 +9,8 @@ Overview
 ``PyLammps`` is a Python wrapper class for LAMMPS which can be created
 on its own or use an existing lammps Python object.  It creates a simpler,
 more "pythonic" interface to common LAMMPS functionality, in contrast to
-the ``lammps.py`` wrapper for the C-style LAMMPS library interface which
-is written using `Python ctypes <ctypes_>`_.  The ``lammps.py`` wrapper
+the ``lammps`` wrapper for the C-style LAMMPS library interface which
+is written using `Python ctypes <ctypes_>`_.  The ``lammps`` wrapper
 is discussed on the :doc:`Python_head` doc page.
 
 Unlike the flat ``ctypes`` interface, PyLammps exposes a discoverable

doc/src/Howto_walls.rst

@@ -67,5 +67,5 @@ rotate.
 
 The only frictional idealized walls currently in LAMMPS are flat or
 curved surfaces specified by the :doc:`fix wall/gran <fix_wall_gran>`
-command.  At some point we plan to allow regoin surfaces to be used as
+command.  At some point we plan to allow region surfaces to be used as
 frictional walls, as well as triangulated surfaces.

doc/src/Install_tarball.rst

@@ -33,22 +33,19 @@ in its name, e.g. lammps-23Jun18.
 
 ----------
 
-You can also download a zip file via the "Clone or download" button on
-the `LAMMPS GitHub site <git_>`_.  The file name will be lammps-master.zip
-which can be unzipped with the following command, to create
-a lammps-master dir:
+You can also download a compressed tar or zip archives from the
+"Assets" sections of the `LAMMPS GitHub releases site <git_>`_.
+The file name will be lammps-<version>.zip which can be unzipped
+with the following command, to create a lammps-<version> dir:
 
 .. code-block:: bash
 
    $ unzip lammps*.zip
 
-This version is the most up-to-date LAMMPS development version.  It
-will have the date of the most recent patch release (see the file
-src/version.h).  But it will also include any new bug-fixes or
-features added since the last patch release.  They will be included in
-the next patch release tarball.
+This version corresponds to the selected LAMMPS patch or stable
+release.
 
-.. _git: https://github.com/lammps/lammps
+.. _git: https://github.com/lammps/lammps/releases
 
 ----------
 

doc/src/Intro_citing.rst

@@ -24,29 +24,32 @@ DOI for the LAMMPS code
 LAMMPS developers use the `Zenodo service at CERN
 <https://zenodo.org/>`_ to create digital object identifies (DOI) for
 stable releases of the LAMMPS code. There are two types of DOIs for the
-LAMMPS source code: 1) the canonical DOI for **all** versions of LAMMPS,
-which will always point to the latest stable release version is:
+LAMMPS source code: the canonical DOI for **all** versions of LAMMPS,
+which will always point to the **latest** stable release version is:
 
-  `DOI: 10.5281/zenodo.3726416 <https://dx.doi/org/10.5281/zenodo.3726416>`_
+- DOI: `10.5281/zenodo.3726416 <https://dx.doi.org/10.5281/zenodo.3726416>`_
 
-In addition there are DOIs for individual stable releases starting with
-the `3 March 2020 version, DOI:10.5281/zenodo.3726417 <https://dx.doi/org/10.5281/zenodo.3726416>`_
+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>`_
 
 
 Home page
 ^^^^^^^^^
 
-The LAMMPS website at `https://lammps.sandia.gov/ <https://lammps.sandia.gov>`_ is the canonical
-location for information about LAMMPS and more detailed lists of publications
-using LAMMPS and contributing features.
+The LAMMPS website at `https://lammps.sandia.gov/
+<https://lammps.sandia.gov>`_ is the canonical location for information
+about LAMMPS and its features.
 
 Citing contributions
 ^^^^^^^^^^^^^^^^^^^^
 
-LAMMPS has many features and uses previously published methods and
-algorithms or novel features. It also includes potential parameter
-filed for specific models.  You can look up relevant publications either
-in the LAMMPS output to the screen, the ``log.cite`` file (which is
-populated with references to relevant papers through embedding them into
-the source code) and in the documentation of the :doc:`corresponding commands
+LAMMPS has many features and that use either previously published
+methods and algorithms or novel features.  It also includes potential
+parameter filed for specific models.  Where available, a reminder about
+references for optional features used in a specific run is printed to
+the screen and log file.  Style and output location can be selected with
+the :ref:`-cite command-line switch <cite>`.  Additional references are
+given in the documentation of the :doc:`corresponding commands
 <Commands_all>` or in the :doc:`Howto tutorials <Howto>`.

doc/src/Intro_features.rst

@@ -85,7 +85,7 @@ commands)
 * water potentials: TIP3P, TIP4P, SPC
 * implicit solvent potentials: hydrodynamic lubrication, Debye
 * force-field compatibility with common CHARMM, AMBER, DREIDING,     OPLS, GROMACS, COMPASS options
-* access to the `OpenKIM Repository <http://openkim.org>`_ of potentials via     :doc:`kim_init, kim_interactions, and kim_query <kim_commands>` commands
+* access to the `OpenKIM Repository <http://openkim.org>`_ of potentials via     :doc:`kim command <kim_commands>`
 * hybrid potentials: multiple pair, bond, angle, dihedral, improper     potentials can be used in one simulation
 * overlaid potentials: superposition of multiple pair potentials
 

doc/src/Library_config.rst

@@ -14,6 +14,7 @@ This section documents the following functions:
 - :cpp:func:`lammps_config_has_package`
 - :cpp:func:`lammps_config_package_count`
 - :cpp:func:`lammps_config_package_name`
+- :cpp:func:`lammps_config_accelerator`
 - :cpp:func:`lammps_has_style`
 - :cpp:func:`lammps_style_count`
 - :cpp:func:`lammps_style_name`
@@ -126,6 +127,11 @@ approach.
 
 -----------------------
 
+.. doxygenfunction:: lammps_config_accelerator
+   :project: progguide
+
+-----------------------
+
 .. doxygenfunction:: lammps_has_style
    :project: progguide
 

doc/src/Modify_contribute.rst

@@ -206,16 +206,22 @@ packages in the src directory for examples. If you are uncertain, please ask.
   algorithm/science behind the feature itself, or its initial usage, or
   its implementation in LAMMPS), you can add the citation to the \*.cpp
   source file.  See src/USER-EFF/atom_vec_electron.cpp for an example.
-  A LaTeX citation is stored in a variable at the top of the file and a
-  single line of code that references the variable is added to the
-  constructor of the class.  Whenever a user invokes your feature from
-  their input script, this will cause LAMMPS to output the citation to a
-  log.cite file and prompt the user to examine the file.  Note that you
-  should only use this for a paper you or your group authored.
-  E.g. adding a cite in the code for a paper by Nose and Hoover if you
-  write a fix that implements their integrator is not the intended
-  usage.  That kind of citation should just be in the doc page you
-  provide.
+  A LaTeX citation is stored in a variable at the top of the file and
+  a single line of code registering this variable is added to the
+  constructor of the class.  If there is additional functionality (which
+  may have been added later) described in a different publication,
+  additional citation descriptions may be added for as long as they
+  are only registered when the corresponding keyword activating this
+  functionality is used.  With these options it is possible to have
+  LAMMPS output a specific citation reminder whenever a user invokes
+  your feature from their input script.  Note that you should only use
+  this for the most relevant paper for a feature and a publication that
+  you or your group authored.  E.g. adding a citation in the code for
+  a paper by Nose and Hoover if you write a fix that implements their
+  integrator is not the intended usage.  That kind of citation should
+  just be included in the documentation page you provide describing
+  your contribution.  If you are not sure what the best option would
+  be, please contact the LAMMPS developers for advice.
 
 Finally, as a general rule-of-thumb, the more clear and
 self-explanatory you make your documentation and README files, and the

doc/src/Packages_details.rst

@@ -367,17 +367,19 @@ KIM package
 
 **Contents:**
 
-This package contains a set of commands that serve as a wrapper on the
+This package contains a command with a set of sub-commands that serve as a
+wrapper on the
 `Open Knowledgebase of Interatomic Models (OpenKIM) <https://openkim.org>`_
 repository of interatomic models (IMs) enabling compatible ones to be used in
 LAMMPS simulations.
 
-This includes :doc:`kim_init <kim_commands>`, and
-:doc:`kim_interactions <kim_commands>` commands to select, initialize and
-instantiate the IM, a :doc:`kim_query <kim_commands>` command to perform web
+
+This includes :doc:`kim init <kim_commands>`, and
+:doc:`kim interactions <kim_commands>` commands to select, initialize and
+instantiate the IM, a :doc:`kim query <kim_commands>` command to perform web
 queries for material property predictions of OpenKIM IMs, a
-:doc:`kim_param <kim_commands>` command to access KIM Model Parameters from
-LAMMPS, and a :doc:`kim_property <kim_commands>` command to write material
+:doc:`kim param <kim_commands>` command to access KIM Model Parameters from
+LAMMPS, and a :doc:`kim property <kim_commands>` command to write material
 properties computed in LAMMPS to standard KIM property instance format.
 
 Support for KIM IMs that conform to the
@@ -386,8 +388,8 @@ is provided by the :doc:`pair_style kim <pair_kim>` command.
 
 .. note::
 
-   The command *pair_style kim* is called by *kim_interactions* and
-   is not recommended to be directly used in input scripts.
+   The command *pair_style kim* is called by *kim interactions* and is not
+   recommended to be directly used in input scripts.
 
 To use this package you must have the KIM API library available on your
 system. The KIM API is available for download on the
@@ -404,7 +406,7 @@ and is funded by the `National Science Foundation <https://www.nsf.gov/>`_.
 API and the *pair_style kim* command. Yaser Afshar (U Minnesota),
 Axel Kohlmeyer (Temple U), Ellad Tadmor (U Minnesota), and
 Daniel Karls (U Minnesota) contributed to the
-:doc:`kim_commands <kim_commands>` interface in close collaboration with
+:doc:`kim command <kim_commands>` interface in close collaboration with
 Ryan Elliott.
 
 **Install:**
@@ -414,7 +416,7 @@ This package has :ref:`specific installation instructions <kim>` on the
 
 **Supporting info:**
 
-* :doc:`kim_commands <kim_commands>`
+* :doc:`kim command <kim_commands>`
 * :doc:`pair_style kim <pair_kim>`
 * src/KIM: filenames -> commands
 * src/KIM/README
@@ -662,19 +664,31 @@ MLIAP package
 
 **Contents:**
 
-A general interface for machine-learning interatomic potentials.
+A general interface for machine-learning interatomic potentials, including PyTorch.
 
 **Install:**
 
-To use this package, also the :ref:`SNAP package <PKG-SNAP>` needs to be installed.
+To use this package, also the :ref:`SNAP package <PKG-SNAP>` package needs
+to be installed.  To make the *mliappy* model available, also the
+:ref:`PYTHON package <PKG-PYTHON>` package needs to be installed, the version
+of Python must be 3.6 or later, and the `cython <https://cython.org/>`_ software
+must be installed.
 
-**Author:** Aidan Thompson (Sandia).
+**Author:** Aidan Thompson (Sandia), Nicholas Lubbers (LANL).
 
 **Supporting info:**
 
 * src/MLIAP: filenames -> commands
+* src/MLIAP/README
 * :doc:`pair_style mliap <pair_mliap>`
-* examples/mliap
+* :doc:`compute_style mliap <compute_mliap>`
+* examples/mliap (see README)
+
+When built with the *mliappy* model this package includes an extension for
+coupling with Python models, including PyTorch. In this case, the Python
+interpreter linked to LAMMPS will need the ``cython`` and ``numpy`` modules
+installed.  The provided examples build models with PyTorch, which would
+therefore also needs to be installed to run those examples.
 
 ----------
 
@@ -1036,9 +1050,11 @@ the usual manner via MD.  Various pair, fix, and compute styles.
 * :doc:`pair_style spin/dipole/long <pair_spin_dipole>`
 * :doc:`pair_style spin/dmi <pair_spin_dmi>`
 * :doc:`pair_style spin/exchange <pair_spin_exchange>`
+* :doc:`pair_style spin/exchange/biquadratic <pair_spin_exchange>`
 * :doc:`pair_style spin/magelec <pair_spin_magelec>`
 * :doc:`pair_style spin/neel <pair_spin_neel>`
 * :doc:`fix nve/spin <fix_nve_spin>`
+* :doc:`fix langevin/spin <fix_langevin_spin>`
 * :doc:`fix precession/spin <fix_precession_spin>`
 * :doc:`compute spin <compute_spin>`
 * :doc:`neb/spin <neb_spin>`
@@ -1416,8 +1432,8 @@ oscillators as a model of polarization.  See the :doc:`Howto drude <Howto_drude>
 for an overview of how to use the package.  There are auxiliary tools
 for using this package in tools/drude.
 
-**Authors:** Alain Dequidt (U Blaise Pascal Clermont-Ferrand), Julien
-Devemy (CNRS), and Agilio Padua (U Blaise Pascal).
+**Authors:** Alain Dequidt (U Clermont Auvergne), Julien
+Devemy (CNRS), and Agilio Padua (ENS de Lyon).
 
 **Supporting info:**
 
@@ -1484,7 +1500,7 @@ methods for performing FEP simulations by using a :doc:`fix adapt/fep <fix_adapt
 which have a "soft" in their style name.  There are auxiliary tools
 for using this package in tools/fep; see its README file.
 
-**Author:** Agilio Padua (Universite Blaise Pascal Clermont-Ferrand)
+**Author:** Agilio Padua (ENS de Lyon)
 
 **Supporting info:**
 

doc/src/Python_atoms.rst

@@ -50,7 +50,7 @@ against invalid accesses.
 
       **Numpy Methods**:
 
-      * :py:meth:`numpy.extract_atom() <lammps.numpy_wrapper.extract_atom()>`: extract a per-atom quantity as numpy array
+      * :py:meth:`numpy.extract_atom() <lammps.numpy_wrapper.numpy_wrapper.extract_atom()>`: extract a per-atom quantity as numpy array
 
    .. tab:: PyLammps/IPyLammps API
 

doc/src/Python_config.rst

@@ -39,7 +39,9 @@ about compile time settings and included packages and styles.
 * :py:attr:`lammps.has_jpeg_support <lammps.lammps.has_jpeg_support>`
 * :py:attr:`lammps.has_ffmpeg_support <lammps.lammps.has_ffmpeg_support>`
 
-* :py:attr:`lammps.installed_packages <lammps.lammps.installed_pages>`
+* :py:attr:`lammps.installed_packages <lammps.lammps.installed_packages>`
+
+* :py:meth:`lammps.get_accelerator_config <lammps.lammps.accelerator_config>`
 
 * :py:meth:`lammps.has_style() <lammps.lammps.has_style()>`
 * :py:meth:`lammps.available_styles() <lammps.lammps.available_styles()>`

doc/src/Python_ext.rst

@@ -9,7 +9,7 @@ This means you can extend the Python wrapper by following these steps:
 * Add a new interface function to ``src/library.cpp`` and
   ``src/library.h``.
 * Rebuild LAMMPS as a shared library.
-* Add a wrapper method to ``python/lammps.py`` for this interface
+* Add a wrapper method to ``python/lammps/core.py`` for this interface
   function.
 * Define the corresponding ``argtypes`` list and ``restype``
   in the ``lammps.__init__()`` function.

doc/src/Python_formats.rst

@@ -0,0 +1,11 @@
+Output Readers
+==============
+
+.. py:module:: lammps.formats
+
+The Python package contains the :py:mod:`lammps.formats` module, which
+provides classes to post-process some of the output files generated by LAMMPS.
+
+.. automodule:: lammps.formats
+   :members:
+   :noindex:

doc/src/Python_head.rst

@@ -13,6 +13,7 @@ together.
    Python_module
    Python_ext
    Python_call
+   Python_formats
    Python_examples
    Python_error
    Python_trouble

doc/src/Python_install.rst

@@ -8,9 +8,9 @@ module.  Because of the dynamic loading, it is required that LAMMPS is
 compiled in :ref:`"shared" mode <exe>`.  It is also recommended to
 compile LAMMPS with :ref:`C++ exceptions <exceptions>` enabled.
 
-Two files are necessary for Python to be able to invoke LAMMPS code:
+Two components are necessary for Python to be able to invoke LAMMPS code:
 
-* The LAMMPS Python Module (``lammps.py``) from the ``python`` folder
+* The LAMMPS Python Package (``lammps``) from the ``python`` folder
 * The LAMMPS Shared Library (``liblammps.so``, ``liblammps.dylib`` or
   ``liblammps.dll``) from the folder where you compiled LAMMPS.
 
@@ -25,10 +25,10 @@ Installing the LAMMPS Python Module and Shared Library
 ======================================================
 
 Making LAMMPS usable within Python and vice versa requires putting the
-LAMMPS Python module file (``lammps.py``) into a location where the
+LAMMPS Python package (``lammps``) into a location where the
 Python interpreter can find it and installing the LAMMPS shared library
-into a folder that the dynamic loader searches or into the same folder
-where the ``lammps.py`` file is.  There are multiple ways to achieve
+into a folder that the dynamic loader searches or inside of the installed
+``lammps`` package folder.  There are multiple ways to achieve
 this.
 
 #. Do a full LAMMPS installation of libraries, executables, selected
@@ -36,13 +36,13 @@ this.
    available via CMake), which can also be either system-wide or into
    user specific folders.
 
-#. Install both files into a Python ``site-packages`` folder, either
+#. Install both components into a Python ``site-packages`` folder, either
    system-wide or in the corresponding user-specific folder. This way no
    additional environment variables need to be set, but the shared
    library is otherwise not accessible.
 
-#. Do an installation into a virtual environment. This can either be
-   an installation of the python module only or a full installation.
+#. Do an installation into a virtual environment. This can either be an
+   installation of the Python package only or a full installation of LAMMPS.
 
 #. Leave the files where they are in the source/development tree and
    adjust some environment variables.
@@ -69,7 +69,7 @@ this.
          cd build
 
          # configure LAMMPS compilation
-         cmake -C cmake/presets/minimal.cmake -D BUILD_SHARED_LIBS=on \
+         cmake -C ../cmake/presets/minimal.cmake -D BUILD_SHARED_LIBS=on \
                -D LAMMPS_EXCEPTIONS=on -D PKG_PYTHON=on ../cmake
 
          # compile LAMMPS
@@ -81,40 +81,42 @@ this.
 
       This leads to an installation to the following locations:
 
-      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
-      | File                   | Location                                                  | Notes                                                       |
-      +========================+===========================================================+=============================================================+
-      | LAMMPS Python Module   | * ``$HOME/.local/lib/pythonX.Y/site-packages/`` (32bit)   | ``X.Y`` depends on the installed Python version             |
-      |                        | * ``$HOME/.local/lib64/pythonX.Y/site-packages/`` (64bit) |                                                             |
-      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
-      | LAMMPS shared library  | * ``$HOME/.local/lib/`` (32bit)                           |                                                             |
-      |                        | * ``$HOME/.local/lib64/`` (64bit)                         |                                                             |
-      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
-      | LAMMPS executable      | * ``$HOME/.local/bin/``                                   |                                                             |
-      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
-      | LAMMPS potential files | * ``$HOME/.local/share/lammps/potentials/``               | Set ``LAMMPS_POTENTIALS`` environment variable to this path |
-      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+      | File                   | Location                                                        | Notes                                                       |
+      +========================+=================================================================+=============================================================+
+      | LAMMPS Python package  | * ``$HOME/.local/lib/pythonX.Y/site-packages/lammps`` (32bit)   | ``X.Y`` depends on the installed Python version             |
+      |                        | * ``$HOME/.local/lib64/pythonX.Y/site-packages/lammps`` (64bit) |                                                             |
+      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+      | LAMMPS shared library  | * ``$HOME/.local/lib/`` (32bit)                                 | Set shared loader environment variable to this path         |
+      |                        | * ``$HOME/.local/lib64/`` (64bit)                               | (see below for more info on this)                           |
+      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+      | LAMMPS executable      | * ``$HOME/.local/bin/``                                         |                                                             |
+      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+      | LAMMPS potential files | * ``$HOME/.local/share/lammps/potentials/``                     | Set ``LAMMPS_POTENTIALS`` environment variable to this path |
+      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
 
       For a system-wide installation you need to set
       ``CMAKE_INSTALL_PREFIX`` to a system folder like ``/usr`` (or
-      ``/usr/local``).  The installation step (**not** the
+      ``/usr/local``); the default is ``${HOME}/.local``.  The
+      installation step for a system folder installation (**not** the
       configuration/compilation) needs to be done with superuser
       privilege, e.g. by using ``sudo cmake --install .``.  The
-      installation folders will then by changed to:
+      installation folders will then be changed to (assuming ``/usr`` as
+      prefix):
 
-      +------------------------+---------------------------------------------------+-------------------------------------------------------------+
-      | File                   | Location                                          | Notes                                                       |
-      +========================+===================================================+=============================================================+
-      | LAMMPS Python Module   | * ``/usr/lib/pythonX.Y/site-packages/`` (32bit)   | ``X.Y`` depends on the installed Python version             |
-      |                        | * ``/usr/lib64/pythonX.Y/site-packages/`` (64bit) |                                                             |
-      +------------------------+---------------------------------------------------+-------------------------------------------------------------+
-      | LAMMPS shared library  | * ``/usr/lib/`` (32bit)                           |                                                             |
-      |                        | * ``/usr/lib64/`` (64bit)                         |                                                             |
-      +------------------------+---------------------------------------------------+-------------------------------------------------------------+
-      | LAMMPS executable      | * ``/usr/bin/``                                   |                                                             |
-      +------------------------+---------------------------------------------------+-------------------------------------------------------------+
-      | LAMMPS potential files | * ``/usr/share/lammps/potentials/``               |                                                             |
-      +------------------------+---------------------------------------------------+-------------------------------------------------------------+
+      +------------------------+---------------------------------------------------------+-------------------------------------------------------------+
+      | File                   | Location                                                | Notes                                                       |
+      +========================+=========================================================+=============================================================+
+      | LAMMPS Python package  | * ``/usr/lib/pythonX.Y/site-packages/lammps`` (32bit)   | ``X.Y`` depends on the installed Python version             |
+      |                        | * ``/usr/lib64/pythonX.Y/site-packages/lammps`` (64bit) |                                                             |
+      +------------------------+---------------------------------------------------------+-------------------------------------------------------------+
+      | LAMMPS shared library  | * ``/usr/lib/`` (32bit)                                 |                                                             |
+      |                        | * ``/usr/lib64/`` (64bit)                               |                                                             |
+      +------------------------+---------------------------------------------------------+-------------------------------------------------------------+
+      | LAMMPS executable      | * ``/usr/bin/``                                         |                                                             |
+      +------------------------+---------------------------------------------------------+-------------------------------------------------------------+
+      | LAMMPS potential files | * ``/usr/share/lammps/potentials/``                     |                                                             |
+      +------------------------+---------------------------------------------------------+-------------------------------------------------------------+
 
       To be able to use the "user" installation you have to ensure that
       the folder containing the LAMMPS shared library is either included
@@ -146,7 +148,7 @@ this.
       necessary due to files installed in system folders that are loaded
       automatically when a login shell is started.
 
-   .. tab:: Python module only
+   .. tab:: Python package only
 
       Compile LAMMPS with either :doc:`CMake <Build_cmake>` or the
       :doc:`traditional make <Build_make>` procedure in :ref:`shared
@@ -157,37 +159,37 @@ this.
 
          make install-python
 
-      This will try to install (only) the shared library and the python
-      module into a system folder and if that fails (due to missing
+      This will try to install (only) the shared library and the Python
+      package into a system folder and if that fails (due to missing
       write permissions) will instead do the installation to a user
       folder under ``$HOME/.local``.  For a system-wide installation you
       would have to gain superuser privilege, e.g. though ``sudo``
 
-      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
-      | File                   | Location                                                  | Notes                                                       |
-      +========================+===========================================================+=============================================================+
-      | LAMMPS Python Module   | * ``$HOME/.local/lib/pythonX.Y/site-packages/`` (32bit)   | ``X.Y`` depends on the installed Python version             |
-      |                        | * ``$HOME/.local/lib64/pythonX.Y/site-packages/`` (64bit) |                                                             |
-      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
-      | LAMMPS shared library  | * ``$HOME/.local/lib/pythonX.Y/site-packages/`` (32bit)   | ``X.Y`` depends on the installed Python version             |
-      |                        | * ``$HOME/.local/lib64/pythonX.Y/site-packages/`` (64bit) |                                                             |
-      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+      | File                   | Location                                                        | Notes                                                       |
+      +========================+=================================================================+=============================================================+
+      | LAMMPS Python package  | * ``$HOME/.local/lib/pythonX.Y/site-packages/lammps`` (32bit)   | ``X.Y`` depends on the installed Python version             |
+      |                        | * ``$HOME/.local/lib64/pythonX.Y/site-packages/lammps`` (64bit) |                                                             |
+      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+      | LAMMPS shared library  | * ``$HOME/.local/lib/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 Module   | * ``/usr/lib/pythonX.Y/site-packages/`` (32bit)   | ``X.Y`` depends on the installed Python version             |
-      |                        | * ``/usr/lib64/pythonX.Y/site-packages/`` (64bit) |                                                             |
-      +------------------------+---------------------------------------------------+-------------------------------------------------------------+
-      | LAMMPS shared library  | * ``/usr/lib/pythonX.Y/site-packages/`` (32bit)   | ``X.Y`` depends on the installed Python version             |
-      |                        | * ``/usr/lib64/pythonX.Y/site-packages/`` (64bit) |                                                             |
-      +------------------------+---------------------------------------------------+-------------------------------------------------------------+
+      +------------------------+---------------------------------------------------------+-------------------------------------------------------------+
+      | File                   | Location                                                | Notes                                                       |
+      +========================+=========================================================+=============================================================+
+      | LAMMPS Python package  | * ``/usr/lib/pythonX.Y/site-packages/lammps`` (32bit)   | ``X.Y`` depends on the installed Python version             |
+      |                        | * ``/usr/lib64/pythonX.Y/site-packages/lammps`` (64bit) |                                                             |
+      +------------------------+---------------------------------------------------------+-------------------------------------------------------------+
+      | LAMMPS shared library  | * ``/usr/lib/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
-      module.
+      package.
 
       For the traditional make process you can override the python
       version to version x.y when calling ``make`` with
@@ -199,9 +201,9 @@ this.
 
       .. code-block:: bash
 
-         $ python install.py -m <python module> -l <shared library> -v <version.h file> [-d <pydir>]
+         $ python install.py -p <python package> -l <shared library> -v <version.h file> [-d <pydir>]
 
-      * The ``-m`` flag points to the ``lammps.py`` python module file to be installed,
+      * 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 ``-d`` flag to a custom (legacy) installation folder
@@ -249,38 +251,38 @@ this.
       When using CMake to build LAMMPS, you need to set
       ``CMAKE_INSTALL_PREFIX`` to the value of the ``$VIRTUAL_ENV``
       environment variable during the configuration step. For the
-      traditional make procedure, not additional steps are needed.
-      After compiling LAMMPS you can do a "Python module only"
+      traditional make procedure, no additional steps are needed.
+      After compiling LAMMPS you can do a "Python package only"
       installation with ``make install-python`` and the LAMMPS Python
-      module and the shared library file are installed into the
+      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/`` (32bit)   | ``X.Y`` depends on the installed Python version             |
-      |                        | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/`` (64bit) |                                                             |
-      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
-      | LAMMPS shared library  | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/`` (32bit)   | ``X.Y`` depends on the installed Python version             |
-      |                        | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/`` (64bit) |                                                             |
-      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+      | File                   | Location                                                        | Notes                                                       |
+      +========================+=================================================================+=============================================================+
+      | LAMMPS Python Module   | * ``$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) |                                                             |
+      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+      | 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/`` (32bit)   | ``X.Y`` depends on the installed Python version             |
-      |                        | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/`` (64bit) |                                                             |
-      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
-      | LAMMPS shared library  | * ``$VIRTUAL_ENV/lib/`` (32bit)                           |                                                             |
-      |                        | * ``$VIRTUAL_ENV/lib64/`` (64bit)                         |                                                             |
-      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
-      | LAMMPS executable      | * ``$VIRTUAL_ENV/bin/``                                   |                                                             |
-      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
-      | LAMMPS potential files | * ``$VIRTUAL_ENV/share/lammps/potentials/``               |                                                             |
-      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+      | File                   | Location                                                        | Notes                                                       |
+      +========================+=================================================================+=============================================================+
+      | LAMMPS Python Module   | * ``$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) |                                                             |
+      +------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+      | 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
@@ -296,15 +298,15 @@ this.
          echo 'export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$LD_LIBRARY_PATH' >> $HOME/myenv/bin/activate
 
          # MacOS
-         echo 'export DYLD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$LD_LIBRARY_PATH' >> $HOME/myenv/bin/activate
+         echo 'export DYLD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$DYLD_LIBRARY_PATH' >> $HOME/myenv/bin/activate
 
    .. tab:: In place usage
 
       You can also :doc:`compile LAMMPS <Build>` as usual in
       :ref:`"shared" mode <exe>` leave the shared library and Python
-      module files inside the source/compilation folders. Instead of
+      package inside the source/compilation folders. Instead of
       copying the files where they can be found, you need to set the environment
-      variables ``PYTHONPATH`` (for the Python module) and
+      variables ``PYTHONPATH`` (for the Python package) and
       ``LD_LIBRARY_PATH`` (or ``DYLD_LIBRARY_PATH`` on MacOS
 
       For Bourne shells (bash, ksh and similar) the commands are:
@@ -325,6 +327,10 @@ this.
       You can make those changes permanent by editing your ``$HOME/.bashrc``
       or ``$HOME/.login`` files, respectively.
 
+      .. note::
+
+         The ``PYTHONPATH`` needs to point to the parent folder that contains the ``lammps`` package!
+
 
 To verify if LAMMPS can be successfully started from Python, start the
 Python interpreter, load the ``lammps`` Python module and create a
@@ -346,7 +352,7 @@ output similar to the following:
 .. note::
 
    Unless you opted for "In place use", you will have to rerun the installation
-   any time you recompile LAMMPS to ensure the latest Python module and shared
+   any time you recompile LAMMPS to ensure the latest Python package and shared
    library are installed and used.
 
 .. note::

doc/src/Python_module.rst

@@ -3,12 +3,12 @@ The ``lammps`` Python module
 
 .. py:module:: lammps
 
-The LAMMPS Python interface is implemented as a module called
-:py:mod:`lammps` in the ``lammps.py`` file in the ``python`` folder of
-the LAMMPS source code distribution.  After compilation of LAMMPS, the
-module can be installed into a Python system folder or a user folder
-with ``make install-python``.  Components of the module can then loaded
-into a Python session with the ``import`` command.
+The LAMMPS Python interface is implemented as a module called :py:mod:`lammps`
+which is defined in the ``lammps`` package in the ``python`` folder of the
+LAMMPS source code distribution.  After compilation of LAMMPS, the module can
+be installed into a Python system folder or a user folder with ``make
+install-python``.  Components of the module can then loaded into a Python
+session with the ``import`` command.
 
 There are multiple Python interface classes in the :py:mod:`lammps` module:
 
@@ -26,6 +26,23 @@ There are multiple Python interface classes in the :py:mod:`lammps` module:
 
 .. _mpi4py_url: https://mpi4py.readthedocs.io
 
+.. admonition:: Version check
+   :class: note
+
+   The :py:mod:`lammps` module stores the version number of the LAMMPS
+   version it is installed from.  When initializing the
+   :py:class:`lammps <lammps.lammps>` class, this version is checked to
+   be the same as the result from :py:func:`lammps.version`, the version
+   of the LAMMPS shared library that the module interfaces to.  If the
+   they are not the same an AttributeError exception is raised since a
+   mismatch of versions (e.g.  due to incorrect use of the
+   ``LD_LIBRARY_PATH`` or ``PYTHONPATH`` environment variables can lead
+   to crashes or data corruption and otherwise incorrect behavior.
+
+.. automodule:: lammps
+   :members:
+   :noindex:
+
 ----------
 
 The ``lammps`` class API
@@ -44,7 +61,7 @@ functions. Below is a detailed documentation of the API.
 .. autoclass:: lammps.lammps
    :members:
 
-.. autoclass:: lammps.numpy_wrapper
+.. autoclass:: lammps.numpy_wrapper::numpy_wrapper
    :members:
 
 ----------
@@ -117,8 +134,8 @@ Style Constants
    to request from computes or fixes. See :cpp:enum:`_LMP_STYLE_CONST`
    for the equivalent constants in the C library interface. Used in
    :py:func:`lammps.extract_compute`, :py:func:`lammps.extract_fix`, and their NumPy variants
-   :py:func:`lammps.numpy.extract_compute() <numpy_wrapper.extract_compute>` and
-   :py:func:`lammps.numpy.extract_fix() <numpy_wrapper.extract_fix>`.
+   :py:func:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.numpy_wrapper.extract_compute>` and
+   :py:func:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.numpy_wrapper.extract_fix>`.
 
 .. _py_type_constants:
 
@@ -132,8 +149,8 @@ Type Constants
    to request  from computes  or fixes.  See :cpp:enum:`_LMP_TYPE_CONST`
    for the equivalent constants in the C library interface. Used in
    :py:func:`lammps.extract_compute`, :py:func:`lammps.extract_fix`, and their NumPy variants
-   :py:func:`lammps.numpy.extract_compute() <numpy_wrapper.extract_compute>` and
-   :py:func:`lammps.numpy.extract_fix() <numpy_wrapper.extract_fix>`.
+   :py:func:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.numpy_wrapper.extract_compute>` and
+   :py:func:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.numpy_wrapper.extract_fix>`.
 
 .. _py_vartype_constants:
 
@@ -153,6 +170,6 @@ Classes representing internal objects
    :members:
    :no-undoc-members:
 
-.. autoclass:: lammps.NumPyNeighList
+.. autoclass:: lammps.numpy_wrapper::NumPyNeighList
    :members:
    :no-undoc-members:

doc/src/Python_neighbor.rst

@@ -14,5 +14,5 @@ Neighbor list access
 
 **NumPy Methods:**
 
-* :py:meth:`lammps.numpy.get_neighlist() <lammps.numpy_wrapper.get_neighlist()>`: Get neighbor list for given index, which uses NumPy arrays for its element neighbor arrays
-* :py:meth:`lammps.numpy.get_neighlist_element_neighbors() <lammps.numpy_wrapper.get_neighlist_element_neighbors()>`: Get element in neighbor list and its neighbors (as numpy array)
+* :py:meth:`lammps.numpy.get_neighlist() <lammps.numpy_wrapper.numpy_wrapper.get_neighlist()>`: Get neighbor list for given index, which uses NumPy arrays for its element neighbor arrays
+* :py:meth:`lammps.numpy.get_neighlist_element_neighbors() <lammps.numpy_wrapper.numpy_wrapper.get_neighlist_element_neighbors()>`: Get element in neighbor list and its neighbors (as numpy array)

doc/src/Python_objects.rst

@@ -36,9 +36,9 @@ computes, fixes, or variables in LAMMPS using the :py:mod:`lammps` module.
       Python subscripting. The values will be zero for atoms not in the
       specified group.
 
-      :py:meth:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.extract_compute()>`,
-      :py:meth:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.extract_fix()>`, and
-      :py:meth:`lammps.numpy.extract_variable() <lammps.numpy_wrapper.extract_variable()>` are
+      :py:meth:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.numpy_wrapper.extract_compute()>`,
+      :py:meth:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.numpy_wrapper.extract_fix()>`, and
+      :py:meth:`lammps.numpy.extract_variable() <lammps.numpy_wrapper.numpy_wrapper.extract_variable()>` are
       equivalent NumPy implementations that return NumPy arrays instead of ``ctypes`` pointers.
 
       The :py:meth:`lammps.set_variable() <lammps.lammps.set_variable()>` method sets an
@@ -54,9 +54,9 @@ computes, fixes, or variables in LAMMPS using the :py:mod:`lammps` module.
 
       **NumPy Methods**:
 
-      * :py:meth:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.extract_compute()>`: extract value(s) from a compute, return arrays as numpy arrays
-      * :py:meth:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.extract_fix()>`: extract value(s) from a fix, return arrays as numpy arrays
-      * :py:meth:`lammps.numpy.extract_variable() <lammps.numpy_wrapper.extract_variable()>`: extract value(s) from a variable, return arrays as numpy arrays
+      * :py:meth:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.numpy_wrapper.extract_compute()>`: extract value(s) from a compute, return arrays as numpy arrays
+      * :py:meth:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.numpy_wrapper.extract_fix()>`: extract value(s) from a fix, return arrays as numpy arrays
+      * :py:meth:`lammps.numpy.extract_variable() <lammps.numpy_wrapper.numpy_wrapper.extract_variable()>`: extract value(s) from a variable, return arrays as numpy arrays
 
 
    .. tab:: PyLammps/IPyLammps API

doc/src/Python_overview.rst

@@ -2,9 +2,9 @@ Overview
 ========
 
 The LAMMPS distribution includes a ``python`` directory with the Python
-code needed to run LAMMPS from Python.  The ``python/lammps.py``
-contains :doc:`the "lammps" Python <Python_module>` that wraps the
-LAMMPS C-library interface.  This file makes it is possible to do the
+code needed to run LAMMPS from Python.  The ``python/lammps`` package
+contains :doc:`the "lammps" Python module <Python_module>` that wraps the
+LAMMPS C-library interface.  This module makes it is possible to do the
 following either from a Python script, or interactively from a Python
 prompt:
 
@@ -20,8 +20,8 @@ have a version of Python that extends Python to enable multiple
 instances of Python to read what you type.
 
 To do all of this, you must build LAMMPS in :ref:`"shared" mode <exe>`
-and make certain that your Python interpreter can find the ``lammps.py``
-file and the LAMMPS shared library file.
+and make certain that your Python interpreter can find the ``lammps``
+Python package and the LAMMPS shared library file.
 
 .. _ctypes: https://docs.python.org/3/library/ctypes.html
 

doc/src/Python_trouble.rst

@@ -33,7 +33,7 @@ the constructor call as follows (see :ref:`python_create_lammps` for more detail
    >>> lmp = lammps(name='mpi')
 
 You can also test the load directly in Python as follows, without
-first importing from the lammps.py file:
+first importing from the ``lammps`` module:
 
 .. code-block:: python
 

doc/src/Run_options.rst

@@ -11,6 +11,7 @@ letter abbreviation can be used:
 * :ref:`-k or -kokkos <run-kokkos>`
 * :ref:`-l or -log <log>`
 * :ref:`-m or -mpicolor <mpicolor>`
+* :ref:`-c or -cite <cite>`
 * :ref:`-nc or -nocite <nocite>`
 * :ref:`-pk or -package <package>`
 * :ref:`-p or -partition <partition>`
@@ -62,15 +63,18 @@ used.
 
 **-in file**
 
-Specify a file to use as an input script.  This is an optional switch
-when running LAMMPS in one-partition mode.  If it is not specified,
-LAMMPS reads its script from standard input, typically from a script
-via I/O redirection; e.g. lmp_linux < in.run.  I/O redirection should
-also work in parallel, but if it does not (in the unlikely case that
-an MPI implementation does not support it), then use the -in flag.
+Specify a file to use as an input script.  This is an optional but
+recommended switch when running LAMMPS in one-partition mode.  If it
+is not specified, LAMMPS reads its script from standard input, typically
+from a script via I/O redirection; e.g. lmp_linux < in.run.
+With many MPI implementations I/O redirection also works in parallel,
+but using the -in flag will always work.
+
 Note that this is a required switch when running LAMMPS in
 multi-partition mode, since multiple processors cannot all read from
-stdin.
+stdin concurrently.  The file name may be "none" for starting
+multi-partition calculations without reading an initial input file
+from the library interface.
 
 ----------
 
@@ -217,14 +221,31 @@ links with from the lib/message directory.  See the
 
 ----------
 
+.. _cite:
+
+**-cite style or file name**
+
+Select how and where to output a reminder about citing contributions
+to the LAMMPS code that were used during the run. Available styles are
+"both", "none", "screen", or "log".  Any flag will be considered a file
+name to write the detailed citation info to.  Default is the "log" style
+where there is a short summary in the screen output and detailed citations
+in BibTeX format in the logfile.  The option "both" selects the detailed
+output for both, "none", the short output for both, and "screen" will
+write the detailed info to the screen and the short version to the log
+file.  If a dedicated citation info file is requested, the screen and
+log file output will be in the short format (same as with "none").
+
+See the :doc:`citation page <Intro_citing>` for more details on
+how to correctly reference and cite LAMMPS.
+
+----------
+
 .. _nocite:
 
 **-nocite**
 
-Disable writing the log.cite file which is normally written to list
-references for specific cite-able features used during a LAMMPS run.
-See the `citation page <https://lammps.sandia.gov/cite.html>`_ for more
-details.
+Disable generating a citation reminder (see above) at all.
 
 ----------
 
@@ -296,7 +317,7 @@ command-line option.
 **-pscreen file**
 
 Specify the base name for the partition screen file, so partition N
-writes screen information to file.N. If file is none, then no
+writes screen information to file.N. If file is "none", then no
 partition screen files are created.  This overrides the filename
 specified in the -screen command-line option.  This option is useful
 when working with large numbers of partitions, allowing the partition

doc/src/Speed_gpu.rst

@@ -1,11 +1,14 @@
 GPU package
 ===========
 
-The GPU package was developed by Mike Brown while at SNL and ORNL
-and his collaborators, particularly Trung Nguyen (now at Northwestern).
-It provides GPU versions of many pair styles and for parts of the
-:doc:`kspace_style pppm <kspace_style>` for long-range Coulombics.
-It has the following general features:
+The GPU package was developed by Mike Brown while at SNL and ORNL (now
+at Intel Corp.) and his collaborators, particularly Trung Nguyen (now at
+Northwestern).  Support for AMD GPUs via HIP was added by Vsevolod Nikolskiy
+and coworkers at HSE University.
+
+The GPU package provides GPU versions of many pair styles and for
+parts of the :doc:`kspace_style pppm <kspace_style>` for long-range
+Coulombics.  It has the following general features:
 
 * It is designed to exploit common GPU hardware configurations where one
   or more GPUs are coupled to many cores of one or more multi-core CPUs,
@@ -24,8 +27,9 @@ It has the following general features:
   force vectors.
 * LAMMPS-specific code is in the GPU package.  It makes calls to a
   generic GPU library in the lib/gpu directory.  This library provides
-  NVIDIA support as well as more general OpenCL support, so that the
-  same functionality is supported on a variety of hardware.
+  either Nvidia support, AMD support, or more general OpenCL support
+  (for Nvidia GPUs, AMD GPUs, Intel GPUs, and multi-core CPUs).
+  so that the same functionality is supported on a variety of hardware.
 
 **Required hardware/software:**
 
@@ -45,12 +49,23 @@ to have the OpenCL headers and the (vendor neutral) OpenCL library installed.
 In OpenCL mode, the acceleration depends on having an `OpenCL Installable Client Driver (ICD) <https://www.khronos.org/news/permalink/opencl-installable-client-driver-icd-loader>`_
 installed. There can be multiple of them for the same or different hardware
 (GPUs, CPUs, Accelerators) installed at the same time. OpenCL refers to those
-as 'platforms'.  The GPU library will select the **first** suitable platform,
-but this can be overridden using the device option of the :doc:`package <package>`
+as 'platforms'.  The GPU library will try to auto-select the best suitable platform,
+but this can be overridden using the platform option of the :doc:`package <package>`
 command. run lammps/lib/gpu/ocl_get_devices to get a list of available
 platforms and devices with a suitable ICD available.
 
-To compute and use this package in HIP mode, you have to have the AMD ROCm
+To compile and use this package for Intel GPUs, OpenCL or the Intel oneAPI
+HPC Toolkit can be installed using linux package managers. The latter also
+provides optimized C++, MPI, and many other libraries and tools. See:
+
+* https://software.intel.com/content/www/us/en/develop/tools/oneapi/hpc-toolkit/download.html
+
+If you do not have a discrete GPU card installed, this package can still provide
+significant speedups on some CPUs that include integrated GPUs. Additionally, for
+many macs, OpenCL is already included with the OS and Makefiles are available
+in the lib/gpu directory.
+
+To compile and use this package in HIP mode, you have to have the AMD ROCm
 software installed. Versions of ROCm older than 3.5 are currently deprecated
 by AMD.
 
@@ -75,10 +90,20 @@ automatically if you create more MPI tasks/node than there are
 GPUs/mode.  E.g. with 8 MPI tasks/node and 2 GPUs, each GPU will be
 shared by 4 MPI tasks.
 
+The GPU package also has limited support for OpenMP for both
+multi-threading and vectorization of routines that are run on the CPUs.
+This requires that the GPU library and LAMMPS are built with flags to
+enable OpenMP support (e.g. -fopenmp). Some styles for time integration
+are also available in the GPU package. These run completely on the CPUs
+in full double precision, but exploit multi-threading and vectorization
+for faster performance.
+
 Use the "-sf gpu" :doc:`command-line switch <Run_options>`, which will
 automatically append "gpu" to styles that support it.  Use the "-pk
 gpu Ng" :doc:`command-line switch <Run_options>` to set Ng = # of
-GPUs/node to use.
+GPUs/node to use. If Ng is 0, the number is selected automatically as
+the number of matching GPUs that have the highest number of compute
+cores.
 
 .. code-block:: bash
 
@@ -87,8 +112,8 @@ GPUs/node to use.
    mpirun -np 48 -ppn 12 lmp_machine -sf gpu -pk gpu 2 -in in.script   # ditto on 4 16-core nodes
 
 Note that if the "-sf gpu" switch is used, it also issues a default
-:doc:`package gpu 1 <package>` command, which sets the number of
-GPUs/node to 1.
+:doc:`package gpu 0 <package>` command, which will result in
+automatic selection of the number of GPUs to use.
 
 Using the "-pk" switch explicitly allows for setting of the number of
 GPUs/node to use and additional options.  Its syntax is the same as
@@ -138,6 +163,13 @@ Likewise, you should experiment with the precision setting for the GPU
 library to see if single or mixed precision will give accurate
 results, since they will typically be faster.
 
+MPI parallelism typically outperforms OpenMP parallelism, but in some
+cases using fewer MPI tasks and multiple OpenMP threads with the GPU
+package can give better performance. 3-body potentials can often perform
+better with multiple OMP threads because the inter-process communication
+is higher for these styles with the GPU package in order to allow
+deterministic results.
+
 **Guidelines for best performance:**
 
 * Using multiple MPI tasks per GPU will often give the best performance,
@@ -161,6 +193,12 @@ results, since they will typically be faster.
   :doc:`angle <angle_style>`, :doc:`dihedral <dihedral_style>`,
   :doc:`improper <improper_style>`, and :doc:`long-range <kspace_style>`
   calculations will not be included in the "Pair" time.
+* Since only part of the pppm kspace style is GPU accelerated, it
+  may be faster to only use GPU acceleration for Pair styles with
+  long-range electrostatics.  See the "pair/only" keyword of the
+  package command for a shortcut to do that.  The work between kspace
+  on the CPU and non-bonded interactions on the GPU can be balanced
+  through adjusting the coulomb cutoff without loss of accuracy.
 * When the *mode* setting for the package gpu command is force/neigh,
   the time for neighbor list calculations on the GPU will be added into
   the "Pair" time, not the "Neigh" time.  An additional breakdown of the

doc/src/Speed_kokkos.rst

@@ -26,6 +26,15 @@ task). These are Serial (MPI-only for CPUs and Intel Phi), OpenMP
 GPUs) and HIP (for AMD GPUs). You choose the mode at build time to
 produce an executable compatible with a specific hardware.
 
+.. admonition:: C++14 support
+      :class: note
+
+   Kokkos requires using a compiler that supports the c++14 standard. For
+   some compilers, it may be necessary to add a flag to enable c++14 support.
+   For example, the GNU compiler uses the -std=c++14 flag. For a list of
+   compilers that have been tested with the Kokkos library, see the Kokkos
+   `README <https://github.com/kokkos/kokkos/blob/master/README.md>`_.
+
 .. admonition:: NVIDIA CUDA support
    :class: note
 
@@ -38,14 +47,14 @@ produce an executable compatible with a specific hardware.
    :class: note
 
    Kokkos with CUDA currently implicitly assumes that the MPI library is
-   CUDA-aware. This is not always the case, especially when using
+   GPU-aware. This is not always the case, especially when using
    pre-compiled MPI libraries provided by a Linux distribution. This is
    not a problem when using only a single GPU with a single MPI
    rank. When running with multiple MPI ranks, you may see segmentation
-   faults without CUDA-aware MPI support. These can be avoided by adding
-   the flags :doc:`-pk kokkos cuda/aware off <Run_options>` to the
+   faults without GPU-aware MPI support. These can be avoided by adding
+   the flags :doc:`-pk kokkos gpu/aware off <Run_options>` to the
    LAMMPS command line or by using the command :doc:`package kokkos
-   cuda/aware off <package>` in the input file.
+   gpu/aware off <package>` in the input file.
 
 .. admonition:: AMD GPU support
    :class: note
@@ -242,8 +251,8 @@ case, also packing/unpacking communication buffers on the host may give
 speedup (see the KOKKOS :doc:`package <package>` command). Using CUDA MPS
 is recommended in this scenario.
 
-Using a CUDA-aware MPI library is highly recommended. CUDA-aware MPI use can be
-avoided by using :doc:`-pk kokkos cuda/aware no <package>`. As above for
+Using a GPU-aware MPI library is highly recommended. GPU-aware MPI use can be
+avoided by using :doc:`-pk kokkos gpu/aware off <package>`. As above for
 multi-core CPUs (and no GPU), if N is the number of physical cores/node,
 then the number of MPI tasks/node should not exceed N.
 

doc/src/Speed_packages.rst

@@ -16,7 +16,7 @@ These are the accelerator packages currently in LAMMPS, either as
 standard or user packages:
 
 +-----------------------------------------+-------------------------------------------------------+
-| :doc:`GPU Package <Speed_gpu>`          | for NVIDIA GPUs as well as OpenCL support             |
+| :doc:`GPU Package <Speed_gpu>`          | for GPUs via CUDA, OpenCL, or ROCm HIP                |
 +-----------------------------------------+-------------------------------------------------------+
 | :doc:`USER-INTEL Package <Speed_intel>` | for Intel CPUs and Intel Xeon Phi                     |
 +-----------------------------------------+-------------------------------------------------------+
@@ -43,7 +43,7 @@ three kinds of hardware, via the listed packages:
 +-----------------+-----------------------------------------------------------------------------------------------------------------------------+
 | Many-core CPUs  | :doc:`USER-INTEL <Speed_intel>`, :doc:`KOKKOS <Speed_kokkos>`, :doc:`USER-OMP <Speed_omp>`, :doc:`OPT <Speed_opt>` packages |
 +-----------------+-----------------------------------------------------------------------------------------------------------------------------+
-| NVIDIA/AMD GPUs | :doc:`GPU <Speed_gpu>`, :doc:`KOKKOS <Speed_kokkos>` packages                                                               |
+| GPUs            | :doc:`GPU <Speed_gpu>`, :doc:`KOKKOS <Speed_kokkos>` packages                                                               |
 +-----------------+-----------------------------------------------------------------------------------------------------------------------------+
 | Intel Phi/AVX   | :doc:`USER-INTEL <Speed_intel>`, :doc:`KOKKOS <Speed_kokkos>` packages                                                      |
 +-----------------+-----------------------------------------------------------------------------------------------------------------------------+
@@ -154,8 +154,8 @@ Here is a brief summary of what the various packages provide.  Details
 are in the individual accelerator sections.
 
 * Styles with a "gpu" suffix are part of the GPU package and can be run
-  on NVIDIA or AMD GPUs.  The speed-up on a GPU depends on a variety of
-  factors, discussed in the accelerator sections.
+  on Intel, NVIDIA, or AMD GPUs.  The speed-up on a GPU depends on a
+  variety of factors, discussed in the accelerator sections.
 * Styles with an "intel" suffix are part of the USER-INTEL
   package. These styles support vectorized single and mixed precision
   calculations, in addition to full double precision.  In extreme cases,

doc/src/Tools.rst

@@ -267,7 +267,7 @@ data file in the required format.
 See the header of the polarizer.py file for details.
 
 The tool is authored by Agilio Padua and Alain Dequidt: agilio.padua
-at univ-bpclermont.fr, alain.dequidt at univ-bpclermont.fr
+at ens-lyon.fr, alain.dequidt at uca.fr
 
 ----------
 
@@ -341,8 +341,7 @@ The tools/fep directory contains Python scripts useful for
 post-processing results from performing free-energy perturbation
 simulations using the USER-FEP package.
 
-The scripts were contributed by Agilio Padua (Universite Blaise
-Pascal Clermont-Ferrand), agilio.padua at univ-bpclermont.fr.
+The scripts were contributed by Agilio Padua (ENS de Lyon), agilio.padua at ens-lyon.fr.
 
 See README file in the tools/fep directory.
 

doc/src/angle_gaussian.rst

@@ -0,0 +1,69 @@
+.. index:: angle_style gaussian
+
+angle_style gaussian command
+================================
+
+Syntax
+""""""
+
+.. code-block:: LAMMPS
+
+   angle_style gaussian
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+   angle_style gaussian
+   angle_coeff 1 300.0 2 0.0128 0.375 80.0 0.0730 0.148 123.0
+
+Description
+"""""""""""
+
+The *gaussian* angle style uses the potential:
+
+.. math::
+
+   E = -k_B T ln\left(\sum_{i=1}^{n} \frac{A_i}{w_i \sqrt{\pi/2}} exp\left( \frac{-(\theta-\theta_{i})^2}{w_i^2})\right) \right)
+
+This analytical form is a suitable potential for obtaining
+mesoscale effective force fields which can reproduce target atomistic distributions :ref:`(Milano) <Milano1>`
+The following coefficients must be defined for each angle type via the
+:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
+the data file or restart files read by the :doc:`read_data <read_data>`
+or :doc:`read_restart <read_restart>` commands:
+
+* T temperature at which the potential was derived
+* :math:`n` (integer >=1)
+* :math:`A_1` (-)
+* :math:`w_1` (-)
+* :math:`\theta_1` (degrees)
+* ...
+* :math:`A_n` (-)
+* :math:`w_n` (-)
+* :math:`\theta_n` (degrees)
+
+
+Restrictions
+""""""""""""
+
+This angle style can only be used if LAMMPS was built with the
+USER-MISC package.  See the :doc:`Build package <Build_package>` doc
+page for more info.
+
+Related commands
+""""""""""""""""
+
+:doc:`angle_coeff <angle_coeff>`
+
+Default
+"""""""
+
+none
+
+----------
+
+.. _Milano1:
+
+**(Milano)** G. Milano, S. Goudeau, F. Mueller-Plathe, J. Polym. Sci. B Polym. Phys. 43, 871 (2005).

doc/src/angle_style.rst

@@ -87,6 +87,7 @@ of (g,i,k,o,t) to indicate which accelerated styles exist.
 * :doc:`dipole <angle_dipole>` - angle that controls orientation of a point dipole
 * :doc:`fourier <angle_fourier>` - angle with multiple cosine terms
 * :doc:`fourier/simple <angle_fourier_simple>` - angle with a single cosine term
+* :doc:`gaussian <angle_gaussian>` - multicentered Gaussian-based angle potential
 * :doc:`harmonic <angle_harmonic>` - harmonic angle
 * :doc:`mm3 <angle_mm3>` - anharmonic angle
 * :doc:`quartic <angle_quartic>` - angle with cubic and quartic terms

doc/src/atc_output.rst

@@ -14,7 +14,7 @@ Syntax
 * AtC fixID = ID of :doc:`fix atc <fix_atc>` instance
 * *output* or *output index* = name of the AtC sub-command
 * filename_prefix = prefix for data files (for *output*)
-* frequency = frequency of output in time-steps (for *output*)
+* frequency = frequency of output in timesteps (for *output*)
 * optional keywords for *output*:
 
   - text = creates text output of index, step and nodal variable values for unique nodes

doc/src/balance.rst

@@ -78,14 +78,16 @@ or particles and thus indirectly the computational cost (load) more
 evenly across processors.  The load balancing is "static" in the sense
 that this command performs the balancing once, before or between
 simulations.  The processor sub-domains will then remain static during
-the subsequent run.  To perform "dynamic" balancing, see the :doc:`fix balance <fix_balance>` command, which can adjust processor
-sub-domain sizes and shapes on-the-fly during a :doc:`run <run>`.
+the subsequent run.  To perform "dynamic" balancing, see the :doc:`fix
+balance <fix_balance>` command, which can adjust processor sub-domain
+sizes and shapes on-the-fly during a :doc:`run <run>`.
 
 Load-balancing is typically most useful if the particles in the
 simulation box have a spatially-varying density distribution or when
 the computational cost varies significantly between different
 particles.  E.g. a model of a vapor/liquid interface, or a solid with
-an irregular-shaped geometry containing void regions, or :doc:`hybrid pair style simulations <pair_hybrid>` which combine pair styles with
+an irregular-shaped geometry containing void regions, or :doc:`hybrid
+pair style simulations <pair_hybrid>` which combine pair styles with
 different computational cost.  In these cases, the LAMMPS default of
 dividing the simulation box volume into a regular-spaced grid of 3d
 bricks, with one equal-volume sub-domain per processor, may assign
@@ -101,13 +103,14 @@ which typically induces a different number of atoms assigned to each
 processor.  Details on the various weighting options and examples for
 how they can be used are :ref:`given below <weighted_balance>`.
 
-Note that the :doc:`processors <processors>` command allows some control
-over how the box volume is split across processors.  Specifically, for
-a Px by Py by Pz grid of processors, it allows choice of Px, Py, and
-Pz, subject to the constraint that Px \* Py \* Pz = P, the total number
-of processors.  This is sufficient to achieve good load-balance for
-some problems on some processor counts.  However, all the processor
-sub-domains will still have the same shape and same volume.
+Note that the :doc:`processors <processors>` command allows some
+control over how the box volume is split across processors.
+Specifically, for a Px by Py by Pz grid of processors, it allows
+choice of Px, Py, and Pz, subject to the constraint that Px \* Py \*
+Pz = P, the total number of processors.  This is sufficient to achieve
+good load-balance for some problems on some processor counts.
+However, all the processor sub-domains will still have the same shape
+and same volume.
 
 The requested load-balancing operation is only performed if the
 current "imbalance factor" in particles owned by each processor
@@ -170,12 +173,12 @@ The method used to perform a load balance is specified by one of the
 listed styles (or more in the case of *x*\ ,\ *y*\ ,\ *z*\ ), which are
 described in detail below.  There are 2 kinds of styles.
 
-The *x*\ , *y*\ , *z*\ , and *shift* styles are "grid" methods which produce
-a logical 3d grid of processors.  They operate by changing the cutting
-planes (or lines) between processors in 3d (or 2d), to adjust the
-volume (area in 2d) assigned to each processor, as in the following 2d
-diagram where processor sub-domains are shown and particles are
-colored by the processor that owns them.
+The *x*\ , *y*\ , *z*\ , and *shift* styles are "grid" methods which
+produce a logical 3d grid of processors.  They operate by changing the
+cutting planes (or lines) between processors in 3d (or 2d), to adjust
+the volume (area in 2d) assigned to each processor, as in the
+following 2d diagram where processor sub-domains are shown and
+particles are colored by the processor that owns them.
 
 .. |balance1| image:: img/balance_uniform.jpg
    :width: 32%
@@ -190,20 +193,20 @@ colored by the processor that owns them.
 
 The leftmost diagram is the default partitioning of the simulation box
 across processors (one sub-box for each of 16 processors); the middle
-diagram is after a "grid" method has been applied.  The *rcb* style is a
-"tiling" method which does not produce a logical 3d grid of processors.
-Rather it tiles the simulation domain with rectangular sub-boxes of
-varying size and shape in an irregular fashion so as to have equal
-numbers of particles (or weight) in each sub-box, as in the rightmost
-diagram above.
+diagram is after a "grid" method has been applied.  The *rcb* style is
+a "tiling" method which does not produce a logical 3d grid of
+processors.  Rather it tiles the simulation domain with rectangular
+sub-boxes of varying size and shape in an irregular fashion so as to
+have equal numbers of particles (or weight) in each sub-box, as in the
+rightmost diagram above.
 
-The "grid" methods can be used with either of the
-:doc:`comm_style <comm_style>` command options, *brick* or *tiled*\ .  The
-"tiling" methods can only be used with :doc:`comm_style tiled <comm_style>`.  Note that it can be useful to use a "grid"
-method with :doc:`comm_style tiled <comm_style>` to return the domain
-partitioning to a logical 3d grid of processors so that "comm_style
-brick" can afterwords be specified for subsequent :doc:`run <run>`
-commands.
+The "grid" methods can be used with either of the :doc:`comm_style
+<comm_style>` command options, *brick* or *tiled*\ .  The "tiling"
+methods can only be used with :doc:`comm_style tiled <comm_style>`.
+Note that it can be useful to use a "grid" method with
+:doc:`comm_style tiled <comm_style>` to return the domain partitioning
+to a logical 3d grid of processors so that "comm_style brick" can
+afterwords be specified for subsequent :doc:`run <run>` commands.
 
 When a "grid" method is specified, the current domain partitioning can
 be either a logical 3d grid or a tiled partitioning.  In the former
@@ -280,6 +283,14 @@ information, so that they become closer together over time.  Thus as
 the recursion progresses, the count of particles on either side of the
 plane gets closer to the target value.
 
+After the balanced plane positions are determined, if any pair of
+adjacent planes are closer together than the neighbor skin distance
+(as specified by the :doc`neigh_modify <neigh_modify>` command), then
+the plane positions are shifted to separate them by at least this
+amount.  This is to prevent particles being lost when dynamics are run
+with processor sub-domains that are too narrow in one or more
+dimensions.
+
 Once the re-balancing is complete and final processor sub-domains
 assigned, particles are migrated to their new owning processor, and
 the balance procedure ends.
@@ -293,7 +304,7 @@ the balance procedure ends.
    *Niter* is specified as 10, the cutting plane will typically be
    positioned to 1 part in 1000 accuracy (relative to the perfect target
    position).  For *Niter* = 20, it will be accurate to 1 part in a
-   million.  Thus there is no need ot set *Niter* to a large value.
+   million.  Thus there is no need to set *Niter* to a large value.
    LAMMPS will check if the threshold accuracy is reached (in a
    dimension) is less iterations than *Niter* and exit early.  However,
    *Niter* should also not be set too small, since it will take roughly
@@ -416,7 +427,8 @@ The *time* weight style uses :doc:`timer data <timer>` to estimate
 weights.  It assigns the same weight to each particle owned by a
 processor based on the total computational time spent by that
 processor.  See details below on what time window is used.  It uses
-the same timing information as is used for the :doc:`MPI task timing breakdown <Run_output>`, namely, for sections *Pair*\ , *Bond*\ ,
+the same timing information as is used for the :doc:`MPI task timing
+breakdown <Run_output>`, namely, for sections *Pair*\ , *Bond*\ ,
 *Kspace*\ , and *Neigh*\ .  The time spent in those portions of the
 timestep are measured for each MPI rank, summed, then divided by the
 number of particles owned by that processor.  I.e. the weight is an

doc/src/bond_gaussian.rst

@@ -0,0 +1,70 @@
+.. index:: bond_style gaussian
+
+bond_style gaussian command
+================================
+
+Syntax
+""""""
+
+.. code-block:: LAMMPS
+
+   bond_style gaussian
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+   bond_style gaussian
+   bond_coeff 1 300.0 2 0.0128 0.375 3.37 0.0730 0.148 3.63
+
+Description
+"""""""""""
+
+The *gaussian* bond style uses the potential:
+
+.. math::
+
+   E = -k_B T ln\left(\sum_{i=1}^{n} \frac{A_i}{w_i \sqrt{\pi/2}} exp\left( \frac{-(r-r_{i})^2}{w_i^2})\right) \right)
+
+This analytical form is a suitable potential for obtaining
+mesoscale effective force fields which can reproduce target atomistic distributions :ref:`(Milano) <Milano0>`
+
+The following coefficients must be defined for each bond type via the
+:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
+the data file or restart files read by the :doc:`read_data <read_data>`
+or :doc:`read_restart <read_restart>` commands:
+
+* T temperature at which the potential was derived
+* :math:`n` (integer >=1)
+* :math:`A_1` (-)
+* :math:`w_1` (-)
+* :math:`r_1` (length)
+* ...
+* :math:`A_n` (-)
+* :math:`w_n` (-)
+* :math:`r_n` (length)
+
+
+Restrictions
+""""""""""""
+
+This bond style can only be used if LAMMPS was built with the
+USER-MISC package.  See the :doc:`Build package <Build_package>` doc
+page for more info.
+
+Related commands
+""""""""""""""""
+
+:doc:`bond_coeff <bond_coeff>`
+
+Default
+"""""""
+
+none
+
+----------
+
+.. _Milano0:
+
+**(Milano)** G. Milano, S. Goudeau, F. Mueller-Plathe, J. Polym. Sci. B Polym. Phys. 43, 871 (2005).

doc/src/bond_style.rst

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

doc/src/change_box.rst

@@ -301,9 +301,13 @@ command.
 
 .. note::
 
-   Changing a periodic boundary to a non-periodic one will also
-   cause the image flag for that dimension to be reset to 0 for
-   all atoms.  LAMMPS will print a warning message, if that happens.
+   Changing a periodic boundary to a non-periodic one will also cause
+   the image flag for that dimension of all atoms to be reset to 0.
+   LAMMPS will print a warning message, if that happens.
+   Please note that this reset can lead to undesired changes when
+   atoms are involved in bonded interactions that straddle periodic
+   boundaries and thus the values of the image flag differs for those
+   atoms.
 
 ----------
 

doc/src/comm_modify.rst

@@ -84,13 +84,15 @@ information is available, then also a heuristic based on that bond length
 is computed. It is used as communication cutoff, if there is no pair
 style present and no *comm_modify cutoff* command used. Otherwise a
 warning is printed, if this bond based estimate is larger than the
-communication cutoff used. A
+communication cutoff used.
 
 The *cutoff/multi* option is equivalent to *cutoff*\ , but applies to
 communication mode *multi* instead. Since in this case the communication
 cutoffs are determined per atom type, a type specifier is needed and
 cutoff for one or multiple types can be extended. Also ranges of types
-using the usual asterisk notation can be given.
+using the usual asterisk notation can be given. For granular pair styles,
+the default cutoff is set to the sum of the current maximum atomic radii
+for each type.
 
 These are simulation scenarios in which it may be useful or even
 necessary to set a ghost cutoff > neighbor cutoff:

doc/src/compute_displace_atom.rst

@@ -46,11 +46,12 @@ the compute command was issued.  The value of the displacement will be
 .. note::
 
    Initial coordinates are stored in "unwrapped" form, by using the
-   image flags associated with each atom.  See the :doc:`dump custom <dump>` command for a discussion of "unwrapped" coordinates.
-   See the Atoms section of the :doc:`read_data <read_data>` command for a
-   discussion of image flags and how they are set for each atom.  You can
-   reset the image flags (e.g. to 0) before invoking this compute by
-   using the :doc:`set image <set>` command.
+   image flags associated with each atom.  See the :doc:`dump custom
+   <dump>` command for a discussion of "unwrapped" coordinates.  See
+   the Atoms section of the :doc:`read_data <read_data>` command for a
+   discussion of image flags and how they are set for each atom.  You
+   can reset the image flags (e.g. to 0) before invoking this compute
+   by using the :doc:`set image <set>` command.
 
 .. note::
 

doc/src/compute_fep.rst

@@ -163,7 +163,7 @@ the meaning of these parameters:
 +------------------------------------------------------------------------------+-------------------------+------------+
 | :doc:`born <pair_born>`                                                      | a,b,c                   | type pairs |
 +------------------------------------------------------------------------------+-------------------------+------------+
-| :doc:`buck <pair_buck>`                                                      | a,c                     | type pairs |
+| :doc:`buck, buck/coul/cut, buck/coul/long, buck/coul/msm  <pair_buck>`       | a,c                     | type pairs |
 +------------------------------------------------------------------------------+-------------------------+------------+
 | :doc:`buck/mdf <pair_mdf>`                                                   | a,c                     | type pairs |
 +------------------------------------------------------------------------------+-------------------------+------------+

doc/src/compute_mliap.rst

@@ -18,7 +18,7 @@ Syntax
   .. parsed-literal::
 
        *model* values = style
-         style = *linear* or *quadratic*
+         style = *linear* or *quadratic* or *mliappy*
        *descriptor* values = style filename
          style = *sna*
          filename = name of file containing descriptor definitions
@@ -56,13 +56,15 @@ and it is also straightforward to add new descriptor styles.
 The compute *mliap* command must be followed by two keywords
 *model* and *descriptor* in either order.
 
-The *model* keyword is followed by a model style, currently limited to
-either *linear* or *quadratic*.
+The *model* keyword is followed by the model style (*linear*, *quadratic* or *mliappy*).
+The *mliappy* model is only available
+if lammps is built with MLIAPPY package.
 
 The *descriptor* keyword is followed by a descriptor style, and additional arguments.
-Currently the only descriptor style is *sna*, indicating the bispectrum component
-descriptors used by the Spectral Neighbor Analysis Potential (SNAP) potentials of
-:doc:`pair_style snap <pair_snap>`.
+The compute currently supports just one descriptor style, but it is
+is straightforward to add new descriptor styles.
+The SNAP descriptor style *sna* is the same as that used by :doc:`pair_style snap <pair_snap>`,
+including the linear, quadratic, and chem variants.
 A single additional argument specifies the descriptor filename
 containing the parameters and setting used by the SNAP descriptor.
 The descriptor filename usually ends in the *.mliap.descriptor* extension.
@@ -162,9 +164,10 @@ potentials, see the examples in `FitSNAP <https://github.com/FitSNAP/FitSNAP>`_.
 Restrictions
 """"""""""""
 
-This compute is part of the MLIAP package.  It is only enabled if
-LAMMPS was built with that package.  In addition, building LAMMPS with the MLIAP package
+This compute is part of the MLIAP package.  It is only enabled if LAMMPS
+was built with that package. In addition, building LAMMPS with the MLIAP package
 requires building LAMMPS with the SNAP package.
+The *mliappy* model requires building LAMMPS with the PYTHON package.
 See the :doc:`Build package <Build_package>` doc page for more info.
 
 Related commands

doc/src/compute_orientorder_atom.rst

@@ -115,8 +115,8 @@ The optional keyword *chunksize* is only applicable when using the
 the KOKKOS package and is ignored otherwise. This keyword controls
 the number of atoms in each pass used to compute the bond-orientational
 order parameters and is used to avoid running out of memory. For example
-if there are 4000 atoms in the simulation and the *chunksize*
-is set to 2000, the parameter calculation will be broken up
+if there are 32768 atoms in the simulation and the *chunksize*
+is set to 16384, the parameter calculation will be broken up
 into two passes.
 
 The value of :math:`Q_l` is set to zero for atoms not in the
@@ -193,7 +193,7 @@ Default
 
 The option defaults are *cutoff* = pair style cutoff, *nnn* = 12,
 *degrees* = 5 4 6 8 10 12 i.e. :math:`Q_4`, :math:`Q_6`, :math:`Q_8`, :math:`Q_{10}`, and :math:`Q_{12}`,
-*wl* = no, *wl/hat* = no, *components* off, and *chunksize* = 2000
+*wl* = no, *wl/hat* = no, *components* off, and *chunksize* = 16384
 
 ----------
 

doc/src/compute_pressure.rst

@@ -122,8 +122,11 @@ Output info
 This compute calculates a global scalar (the pressure) and a global
 vector of length 6 (pressure tensor), which can be accessed by indices
 1-6.  These values can be used by any command that uses global scalar
-or vector values from a compute as input.  See the :doc:`Howto output <Howto_output>` doc page for an overview of LAMMPS output
-options.
+or vector values from a compute as input.  See the :doc:`Howto output
+<Howto_output>` doc page for an overview of LAMMPS output options.
+
+The ordering of values in the symmetric pressure tensor is as follows:
+pxx, pyy, pzz, pxy, pxz, pyz.
 
 The scalar and vector values calculated by this compute are
 "intensive".  The scalar and vector values will be in pressure

doc/src/compute_reduce_chunk.rst

@@ -30,7 +30,7 @@ Examples
 
 .. code-block:: LAMMPS
 
-   compute 1 all reduce/chunk/atom mychunk min c_cluster
+   compute 1 all reduce/chunk mychunk min c_cluster
 
 Description
 """""""""""
@@ -38,7 +38,7 @@ Description
 Define a calculation that reduces one or more per-atom vectors into
 per-chunk values.  This can be useful for diagnostic output.  Or when
 used in conjunction with the :doc:`compute chunk/spread/atom <compute_chunk_spread_atom>` command it can be
-used ot create per-atom values that induce a new set of chunks with a
+used to create per-atom values that induce a new set of chunks with a
 second :doc:`compute chunk/atom <compute_chunk_atom>` command.  An
 example is given below.
 

doc/src/compute_stress_atom.rst

@@ -33,32 +33,31 @@ Examples
 Description
 """""""""""
 
-Define a computation that computes per-atom stress
-tensor for each atom in a group.  In case of compute *stress/atom*,
-the tensor for each atom is symmetric with 6
-components and is stored as a 6-element vector in the following order:
-:math:`xx`, :math:`yy`, :math:`zz`, :math:`xy`, :math:`xz`, :math:`yz`.
-In case of compute *centroid/stress/atom*,
-the tensor for each atom is asymmetric with 9 components
-and is stored as a 9-element vector in the following order:
-:math:`xx`, :math:`yy`, :math:`zz`, :math:`xy`, :math:`xz`, :math:`yz`,
-:math:`yx`, :math:`zx`, :math:`zy`.
-See the :doc:`compute pressure <compute_pressure>` command if you want the stress tensor
+Define a computation that computes per-atom stress tensor for each
+atom in a group.  In case of compute *stress/atom*, the tensor for
+each atom is symmetric with 6 components and is stored as a 6-element
+vector in the following order: :math:`xx`, :math:`yy`, :math:`zz`,
+:math:`xy`, :math:`xz`, :math:`yz`.  In case of compute
+*centroid/stress/atom*, the tensor for each atom is asymmetric with 9
+components and is stored as a 9-element vector in the following order:
+:math:`xx`, :math:`yy`, :math:`zz`, :math:`xy`, :math:`xz`,
+:math:`yz`, :math:`yx`, :math:`zx`, :math:`zy`.  See the :doc:`compute
+pressure <compute_pressure>` command if you want the stress tensor
 (pressure) of the entire system.
 
-The stress tensor for atom :math:`I` is given by the following formula,
-where :math:`a` and :math:`b` take on values :math:`x`, :math:`y`, :math:`z`
-to generate the components of the tensor:
+The stress tensor for atom :math:`I` is given by the following
+formula, where :math:`a` and :math:`b` take on values :math:`x`,
+:math:`y`, :math:`z` to generate the components of the tensor:
 
 .. math::
 
    S_{ab}  =  - m v_a v_b - W_{ab}
 
-The first term is a kinetic energy contribution for atom :math:`I`.  See
-details below on how the specified *temp-ID* can affect the velocities
-used in this calculation. The second term is the virial
-contribution due to intra and intermolecular interactions,
-where the exact computation details are determined by the compute style.
+The first term is a kinetic energy contribution for atom :math:`I`.
+See details below on how the specified *temp-ID* can affect the
+velocities used in this calculation. The second term is the virial
+contribution due to intra and intermolecular interactions, where the
+exact computation details are determined by the compute style.
 
 In case of compute *stress/atom*, the virial contribution is:
 
@@ -68,29 +67,26 @@ In case of compute *stress/atom*, the virial contribution is:
   & + \frac{1}{3} \sum_{n = 1}^{N_a} (r_{1_a} F_{1_b} + r_{2_a} F_{2_b} + r_{3_a} F_{3_b}) + \frac{1}{4} \sum_{n = 1}^{N_d} (r_{1_a} F_{1_b} + r_{2_a} F_{2_b} + r_{3_a} F_{3_b} + r_{4_a} F_{4_b}) \\
   & + \frac{1}{4} \sum_{n = 1}^{N_i} (r_{1_a} F_{1_b} + r_{2_a} F_{2_b} + r_{3_a} F_{3_b} + r_{4_a} F_{4_b}) + {\rm Kspace}(r_{i_a},F_{i_b}) + \sum_{n = 1}^{N_f} r_{i_a} F_{i_b}
 
-The first term is a pairwise energy
-contribution where :math:`n` loops over the :math:`N_p`
-neighbors of atom :math:`I`, :math:`\mathbf{r}_1` and :math:`\mathbf{r}_2`
-are the positions of the 2 atoms in the pairwise interaction,
-and :math:`\mathbf{F}_1` and :math:`\mathbf{F}_2` are the forces
-on the 2 atoms resulting from the pairwise interaction.
-The second term is a bond contribution of
-similar form for the :math:`N_b` bonds which atom :math:`I` is part of.
-There are similar terms for the :math:`N_a` angle, :math:`N_d` dihedral,
-and :math:`N_i` improper interactions atom :math:`I` is part of.
-There is also a term for the KSpace
-contribution from long-range Coulombic interactions, if defined.
-Finally, there is a term for the :math:`N_f` :doc:`fixes <fix>` that apply
-internal constraint forces to atom :math:`I`. Currently, only the
-:doc:`fix shake <fix_shake>` and :doc:`fix rigid <fix_rigid>` commands
-contribute to this term.
-As the coefficients in the formula imply, a virial contribution
-produced by a small set of atoms (e.g. 4 atoms in a dihedral or 3
-atoms in a Tersoff 3-body interaction) is assigned in equal portions
-to each atom in the set.  E.g. 1/4 of the dihedral virial to each of
-the 4 atoms, or 1/3 of the fix virial due to SHAKE constraints applied
-to atoms in a water molecule via the :doc:`fix shake <fix_shake>`
-command.
+The first term is a pairwise energy contribution where :math:`n` loops
+over the :math:`N_p` neighbors of atom :math:`I`, :math:`\mathbf{r}_1`
+and :math:`\mathbf{r}_2` are the positions of the 2 atoms in the
+pairwise interaction, and :math:`\mathbf{F}_1` and
+:math:`\mathbf{F}_2` are the forces on the 2 atoms resulting from the
+pairwise interaction.  The second term is a bond contribution of
+similar form for the :math:`N_b` bonds which atom :math:`I` is part
+of.  There are similar terms for the :math:`N_a` angle, :math:`N_d`
+dihedral, and :math:`N_i` improper interactions atom :math:`I` is part
+of.  There is also a term for the KSpace contribution from long-range
+Coulombic interactions, if defined.  Finally, there is a term for the
+:math:`N_f` :doc:`fixes <fix>` that apply internal constraint forces
+to atom :math:`I`. Currently, only the :doc:`fix shake <fix_shake>`
+and :doc:`fix rigid <fix_rigid>` commands contribute to this term.  As
+the coefficients in the formula imply, a virial contribution produced
+by a small set of atoms (e.g. 4 atoms in a dihedral or 3 atoms in a
+Tersoff 3-body interaction) is assigned in equal portions to each atom
+in the set.  E.g. 1/4 of the dihedral virial to each of the 4 atoms,
+or 1/3 of the fix virial due to SHAKE constraints applied to atoms in
+a water molecule via the :doc:`fix shake <fix_shake>` command.
 
 In case of compute *centroid/stress/atom*, the virial contribution is:
 
@@ -99,71 +95,69 @@ In case of compute *centroid/stress/atom*, the virial contribution is:
    W_{ab} & = \sum_{n = 1}^{N_p} r_{I0_a} F_{I_b} + \sum_{n = 1}^{N_b} r_{I0_a} F_{I_b} + \sum_{n = 1}^{N_a} r_{I0_a}  F_{I_b} + \sum_{n = 1}^{N_d} r_{I0_a} F_{I_b} + \sum_{n = 1}^{N_i} r_{I0_a} F_{I_b} \\
   & + {\rm Kspace}(r_{i_a},F_{i_b}) + \sum_{n = 1}^{N_f} r_{i_a} F_{i_b}
 
-As with compute *stress/atom*, the first, second, third, fourth and fifth terms
-are pairwise, bond, angle, dihedral and improper contributions,
-but instead of assigning the virial contribution equally to each atom,
-only the force :math:`\mathbf{F}_I` acting on atom :math:`I`
-due to the interaction and the relative
-position :math:`\mathbf{r}_{I0}` of the atom :math:`I` to the geometric center
-of the interacting atoms, i.e. centroid, is used.
-As the geometric center is different
-for each interaction, the :math:`\mathbf{r}_{I0}` also differs.
-The sixth and seventh terms, Kspace and :doc:`fix <fix>` contribution
-respectively, are computed identical to compute *stress/atom*.
-Although the total system virial is the same as compute *stress/atom*,
-compute *centroid/stress/atom* is know to result in more consistent
-heat flux values for angle, dihedrals and improper contributions
-when computed via :doc:`compute heat/flux <compute_heat_flux>`.
+As with compute *stress/atom*, the first, second, third, fourth and
+fifth terms are pairwise, bond, angle, dihedral and improper
+contributions, but instead of assigning the virial contribution
+equally to each atom, only the force :math:`\mathbf{F}_I` acting on
+atom :math:`I` due to the interaction and the relative position
+:math:`\mathbf{r}_{I0}` of the atom :math:`I` to the geometric center
+of the interacting atoms, i.e. centroid, is used.  As the geometric
+center is different for each interaction, the :math:`\mathbf{r}_{I0}`
+also differs.  The sixth and seventh terms, Kspace and :doc:`fix
+<fix>` contribution respectively, are computed identical to compute
+*stress/atom*.  Although the total system virial is the same as
+compute *stress/atom*, compute *centroid/stress/atom* is know to
+result in more consistent heat flux values for angle, dihedrals and
+improper contributions when computed via :doc:`compute heat/flux
+<compute_heat_flux>`.
 
-If no extra keywords are listed, the kinetic contribution
-all of the virial contribution terms are
-included in the per-atom stress tensor.  If any extra keywords are
-listed, only those terms are summed to compute the tensor.  The
-*virial* keyword means include all terms except the kinetic energy
-*ke*\ .
+If no extra keywords are listed, the kinetic contribution all of the
+virial contribution terms are included in the per-atom stress tensor.
+If any extra keywords are listed, only those terms are summed to
+compute the tensor.  The *virial* keyword means include all terms
+except the kinetic energy *ke*\ .
 
 Note that the stress for each atom is due to its interaction with all
 other atoms in the simulation, not just with other atoms in the group.
 
-Details of how compute *stress/atom* obtains the virial for individual atoms for
-either pairwise or many-body potentials, and including the effects of
-periodic boundary conditions is discussed in :ref:`(Thompson) <Thompson2>`.
-The basic idea for many-body potentials is to treat each component of
-the force computation between a small cluster of atoms in the same
-manner as in the formula above for bond, angle, dihedral, etc
-interactions.  Namely the quantity :math:`\mathbf{r} \cdot \mathbf{F}`
-is summed over the atoms in
-the interaction, with the :math:`r` vectors unwrapped by periodic boundaries
-so that the cluster of atoms is close together.  The total
+Details of how compute *stress/atom* obtains the virial for individual
+atoms for either pairwise or many-body potentials, and including the
+effects of periodic boundary conditions is discussed in
+:ref:`(Thompson) <Thompson2>`.  The basic idea for many-body
+potentials is to treat each component of the force computation between
+a small cluster of atoms in the same manner as in the formula above
+for bond, angle, dihedral, etc interactions.  Namely the quantity
+:math:`\mathbf{r} \cdot \mathbf{F}` is summed over the atoms in the
+interaction, with the :math:`r` vectors unwrapped by periodic
+boundaries so that the cluster of atoms is close together.  The total
 contribution for the cluster interaction is divided evenly among those
-atoms. Details of how compute *centroid/stress/atom* obtains
-the virial for individual atoms
-is given in :ref:`(Surblys) <Surblys1>`,
-where the idea is that the virial of the atom :math:`I`
-is the result of only the force :math:`\mathbf{F}_I` on the atom due
-to the interaction
-and its positional vector :math:`\mathbf{r}_{I0}`,
-relative to the geometric center of the
-interacting atoms, regardless of the number of participating atoms.
-The periodic boundary treatment is identical to
+atoms.
+
+Details of how compute *centroid/stress/atom* obtains the virial for
+individual atoms is given in :ref:`(Surblys) <Surblys1>`, where the
+idea is that the virial of the atom :math:`I` is the result of only
+the force :math:`\mathbf{F}_I` on the atom due to the interaction and
+its positional vector :math:`\mathbf{r}_{I0}`, relative to the
+geometric center of the interacting atoms, regardless of the number of
+participating atoms.  The periodic boundary treatment is identical to
 that of compute *stress/atom*, and both of them reduce to identical
-expressions for two-body interactions,
-i.e. computed values for contributions from bonds and two-body pair styles,
-such as :doc:`Lennard-Jones <pair_lj>`, will be the same,
-while contributions from angles, dihedrals and impropers will be different.
+expressions for two-body interactions, i.e. computed values for
+contributions from bonds and two-body pair styles, such as
+:doc:`Lennard-Jones <pair_lj>`, will be the same, while contributions
+from angles, dihedrals and impropers will be different.
 
 The :doc:`dihedral_style charmm <dihedral_charmm>` style calculates
 pairwise interactions between 1-4 atoms.  The virial contribution of
 these terms is included in the pair virial, not the dihedral virial.
 
 The KSpace contribution is calculated using the method in
-:ref:`(Heyes) <Heyes2>` for the Ewald method and by the methodology described
-in :ref:`(Sirk) <Sirk1>` for PPPM.  The choice of KSpace solver is specified
-by the :doc:`kspace_style pppm <kspace_style>` command.  Note that for
-PPPM, the calculation requires 6 extra FFTs each timestep that
-per-atom stress is calculated.  Thus it can significantly increase the
-cost of the PPPM calculation if it is needed on a large fraction of
-the simulation timesteps.
+:ref:`(Heyes) <Heyes2>` for the Ewald method and by the methodology
+described in :ref:`(Sirk) <Sirk1>` for PPPM.  The choice of KSpace
+solver is specified by the :doc:`kspace_style pppm <kspace_style>`
+command.  Note that for PPPM, the calculation requires 6 extra FFTs
+each timestep that per-atom stress is calculated.  Thus it can
+significantly increase the cost of the PPPM calculation if it is
+needed on a large fraction of the simulation timesteps.
 
 The *temp-ID* argument can be used to affect the per-atom velocities
 used in the kinetic energy contribution to the total stress.  If the
@@ -189,10 +183,10 @@ See the :doc:`compute voronoi/atom <compute_voronoi_atom>` command for
 one possible way to estimate a per-atom volume.
 
 Thus, if the diagonal components of the per-atom stress tensor are
-summed for all atoms in the system and the sum is divided by :math:`dV`, where
-:math:`d` = dimension and :math:`V` is the volume of the system,
-the result should be :math:`-P`, where :math:`P`
-is the total pressure of the system.
+summed for all atoms in the system and the sum is divided by
+:math:`dV`, where :math:`d` = dimension and :math:`V` is the volume of
+the system, the result should be :math:`-P`, where :math:`P` is the
+total pressure of the system.
 
 These lines in an input script for a 3d system should yield that
 result. I.e. the last 2 columns of thermo output will be the same:
@@ -207,33 +201,48 @@ result. I.e. the last 2 columns of thermo output will be the same:
 .. note::
 
    The per-atom stress does not include any Lennard-Jones tail
-   corrections to the pressure added by the :doc:`pair_modify tail yes <pair_modify>` command, since those are contributions to the
-   global system pressure.
+   corrections to the pressure added by the :doc:`pair_modify tail yes
+   <pair_modify>` command, since those are contributions to the global
+   system pressure.
 
 Output info
 """""""""""
 
-This compute *stress/atom* calculates a per-atom array with 6 columns, which can be
-accessed by indices 1-6 by any command that uses per-atom values from
-a compute as input.
-The compute *centroid/stress/atom* produces a per-atom array with 9 columns,
-but otherwise can be used in an identical manner to compute *stress/atom*.
-See the :doc:`Howto output <Howto_output>` doc page
-for an overview of LAMMPS output options.
+Compute *stress/atom* calculates a per-atom array with 6 columns,
+which can be accessed by indices 1-6 by any command that uses per-atom
+values from a compute as input.  Compute *centroid/stress/atom*
+produces a per-atom array with 9 columns, but otherwise can be used in
+an identical manner to compute *stress/atom*.  See the :doc:`Howto
+output <Howto_output>` doc page for an overview of LAMMPS output
+options.
 
-The per-atom array values will be in pressure\*volume
-:doc:`units <units>` as discussed above.
+The ordering of the 6 columns for *stress/atom* is as follows: xx, yy,
+zz, xy, xz, yz.  The ordering of the 9 columns for
+*centroid/stress/atom* is as follows: xx, yy, zz, xy, xz, yz, yx, zx,
+zy.
+
+The per-atom array values will be in pressure\*volume :doc:`units
+<units>` as discussed above.
 
 Restrictions
 """"""""""""
 
-Currently (Spring 2020), compute *centroid/stress/atom* does not support
-pair styles with many-body interactions, such as :doc:`Tersoff
-<pair_tersoff>`, or pair styles with long-range Coulomb interactions.
-LAMMPS will generate an error in such cases.  In principal, equivalent
-formulation to that of angle, dihedral and improper contributions in the
-virial :math:`W_{ab}` formula can also be applied to the many-body pair
-styles, and is planned in the future.
+Currently, compute *centroid/stress/atom* does not support pair styles
+with many-body interactions (:doc:`EAM <pair_eam>` is an exception,
+since its computations are performed pairwise), nor granular pair
+styles with pairwise forces which are not aligned with the vector
+between the pair of particles.  All bond styles are supported.  All
+angle, dihedral, improper styles are supported with the exception of
+USER-INTEL and KOKKOS variants of specific styles.  It also does not
+support models with long-range Coulombic or dispersion forces,
+i.e. the kspace_style command in LAMMPS.  It also does not support the
+following fixes which add rigid-body constraints: :doc:`fix shake
+<fix_shake>`, :doc:`fix rattle <fix_shake>`, :doc:`fix rigid
+<fix_rigid>`, :doc:`fix rigid/small <fix_rigid>`.
+
+LAMMPS will generate an error if one of these options is included in
+your model.  Extension of centroid stress calculations to these force
+and fix styles is planned for the future.
 
 Related commands
 """"""""""""""""

doc/src/compute_temp_chunk.rst

@@ -153,7 +153,7 @@ temp/chunk calculation to a file is to use the :doc:`fix ave/time <fix_ave_time>
 
    compute cc1 all chunk/atom molecule
    compute myChunk all temp/chunk cc1 temp
-   fix 1 all ave/time 100 1 100 c_myChunk file tmp.out mode vector
+   fix 1 all ave/time 100 1 100 c_myChunk[1] file tmp.out mode vector
 
 ----------
 

doc/src/create_bonds.rst

@@ -125,6 +125,16 @@ cannot appear in the neighbor list, to avoid creation of duplicate
 bonds.  The neighbor list for all atom type pairs must also extend to
 a distance that encompasses the *rmax* for new bonds to create.
 
+.. note::
+
+   If you want to create bonds between pairs of 1-3 or 1-4 atoms in
+   the current bond topology, then you need to use :doc:`special_bonds
+   lj 0 1 1 <special_bonds>` to insure those pairs appear in the
+   neighbor list.  They will not appear with the default special_bonds
+   settings which are zero for 1-2, 1-3, and 1-4 atoms.  1-3 or 1-4
+   atoms are those which are 2 hops or 3 hops apart in the bond
+   topology.
+
 An additional requirement for this style is that your system must be
 ready to perform a simulation.  This means, for example, that all
 :doc:`pair_style <pair_style>` coefficients be set via the

doc/src/create_box.rst

@@ -13,7 +13,7 @@ Syntax
 * N = # of atom types to use in this simulation
 * region-ID = ID of region to use as simulation domain
 * zero or more keyword/value pairs may be appended
-* keyword = *bond/types* or *angle/types* or *dihedral/types* or *improper/types* or *extra/bond/per/atom* or *extra/angle/per/atom* or *extra/dihedral/per/atom* or *extra/improper/per/atom*
+* keyword = *bond/types* or *angle/types* or *dihedral/types* or *improper/types* or *extra/bond/per/atom* or *extra/angle/per/atom* or *extra/dihedral/per/atom* or *extra/improper/per/atom* or *extra/special/per/atom*
 
   .. parsed-literal::
 

doc/src/fix.rst

@@ -205,6 +205,7 @@ accelerated styles exist.
 * :doc:`efield <fix_efield>` - impose electric field on system
 * :doc:`ehex <fix_ehex>` - enhanced heat exchange algorithm
 * :doc:`electron/stopping <fix_electron_stopping>` - electronic stopping power as a friction force
+* :doc:`electron/stopping/fit <fix_electron_stopping>` - electronic stopping power as a friction force
 * :doc:`enforce2d <fix_enforce2d>` - zero out z-dimension velocity and force
 * :doc:`eos/cv <fix_eos_cv>` -
 * :doc:`eos/table <fix_eos_table>` -
@@ -363,6 +364,8 @@ accelerated styles exist.
 * :doc:`temp/rescale <fix_temp_rescale>` - temperature control by velocity rescaling
 * :doc:`temp/rescale/eff <fix_temp_rescale_eff>` - temperature control by velocity rescaling in the electron force field model
 * :doc:`tfmc <fix_tfmc>` - perform force-bias Monte Carlo with time-stamped method
+* :doc:`tgnvt/drude <fix_tgnh_drude>` - NVT time integration for Drude polarizable model via temperature-grouped Nose-Hoover
+* :doc:`tgnpt/drude <fix_tgnh_drude>` - NPT time integration for Drude polarizable model via temperature-grouped Nose-Hoover
 * :doc:`thermal/conductivity <fix_thermal_conductivity>` - Muller-Plathe kinetic energy exchange for thermal conductivity calculation
 * :doc:`ti/spring <fix_ti_spring>` -
 * :doc:`tmd <fix_tmd>` - guide a group of atoms to a new configuration

doc/src/fix_adapt.rst

@@ -128,9 +128,9 @@ formulas for the meaning of these parameters:
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`born/coul/long, born/coul/msm <pair_born>`                             | coulombic_cutoff                                 | type global |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
-| :doc:`buck <pair_buck>`                                                      | a,c                                              | type pairs  |
+| :doc:`buck, buck/coul/cut  <pair_buck>`                                      | a,c                                              | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
-| :doc:`buck/coul/long, buck/coul/msm <pair_buck>`                             | coulombic_cutoff                                 | type global |
+| :doc:`buck/coul/long, buck/coul/msm <pair_buck>`                             | a,c,coulombic_cutoff                             | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+
 | :doc:`buck/mdf <pair_mdf>`                                                   | a,c                                              | type pairs  |
 +------------------------------------------------------------------------------+--------------------------------------------------+-------------+

doc/src/fix_adapt_fep.rst

@@ -120,7 +120,7 @@ styles and their energy formulas for the meaning of these parameters:
 +------------------------------------------------------------------------------+-------------------------+------------+
 | :doc:`born <pair_born>`                                                      | a,b,c                   | type pairs |
 +------------------------------------------------------------------------------+-------------------------+------------+
-| :doc:`buck <pair_buck>`                                                      | a,c                     | type pairs |
+| :doc:`buck, buck/coul/cut, buck/coul/long, buck/coul/msm  <pair_buck>`       | a,c                     | type pairs |
 +------------------------------------------------------------------------------+-------------------------+------------+
 | :doc:`buck/mdf <pair_mdf>`                                                   | a,c                     | type pairs |
 +------------------------------------------------------------------------------+-------------------------+------------+

doc/src/fix_addforce.rst

@@ -118,32 +118,38 @@ converge properly.
 Restart, fix_modify, output, run start/stop, minimize info
 """""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
-No information about this fix is written to :doc:`binary restart files <restart>`.
+No information about this fix is written to :doc:`binary restart files
+<restart>`.
 
-The :doc:`fix_modify <fix_modify>` *energy* option is supported by this
-fix to add the potential "energy" inferred by the added force to the
-system's potential energy as part of :doc:`thermodynamic output <thermo_style>`.  This is a fictitious quantity but is
-needed so that the :doc:`minimize <minimize>` command can include the
-forces added by this fix in a consistent manner.  I.e. there is a
-decrease in potential energy when atoms move in the direction of the
-added force.
+The :doc:`fix_modify <fix_modify>` *energy* option is supported by
+this fix to add the potential energy inferred by the added force to
+the global potential energy of the system as part of
+:doc:`thermodynamic output <thermo_style>`.  The default setting for
+this fix is :doc:`fix_modify energy no <fix_modify>`.  Note that this
+energy is a fictitious quantity but is needed so that the
+:doc:`minimize <minimize>` command can include the forces added by
+this fix in a consistent manner.  I.e. there is a decrease in
+potential energy when atoms move in the direction of the added force.
 
-The :doc:`fix_modify <fix_modify>` *virial* option is supported by this
-fix to add the contribution due to the added forces on atoms to the
-system's virial as part of :doc:`thermodynamic output <thermo_style>`.
-The default is *virial no*
+The :doc:`fix_modify <fix_modify>` *virial* option is supported by
+this fix to add the contribution due to the added forces on atoms to
+both the global pressure and per-atom stress of the system via the
+:doc:`compute pressure <compute_pressure>` and :doc:`compute
+stress/atom <compute_stress_atom>` commands.  The former can be
+accessed by :doc:`thermodynamic output <thermo_style>`.  The default
+setting for this fix is :doc:`fix_modify virial no <fix_modify>`.
 
 The :doc:`fix_modify <fix_modify>` *respa* option is supported by this
-fix. This allows to set at which level of the :doc:`r-RESPA <run_style>`
-integrator the fix is adding its forces. Default is the outermost
-level.
+fix. This allows to set at which level of the :doc:`r-RESPA
+<run_style>` integrator the fix is adding its forces. Default is the
+outermost level.
 
 This fix computes a global scalar and a global 3-vector of forces,
-which can be accessed by various :doc:`output commands <Howto_output>`.
-The scalar is the potential energy discussed above.  The vector is the
-total force on the group of atoms before the forces on individual
-atoms are changed by the fix.  The scalar and vector values calculated
-by this fix are "extensive".
+which can be accessed by various :doc:`output commands
+<Howto_output>`.  The scalar is the potential energy discussed above.
+The vector is the total force on the group of atoms before the forces
+on individual atoms are changed by the fix.  The scalar and vector
+values calculated by this fix are "extensive".
 
 No parameter of this fix can be used with the *start/stop* keywords of
 the :doc:`run <run>` command.

doc/src/fix_addtorque.rst

@@ -55,13 +55,15 @@ Restart, fix_modify, output, run start/stop, minimize info
 
 No information about this fix is written to :doc:`binary restart files <restart>`.
 
-The :doc:`fix_modify <fix_modify>` *energy* option is supported by this
-fix to add the potential "energy" inferred by the added forces to the
-system's potential energy as part of :doc:`thermodynamic output <thermo_style>`.  This is a fictitious quantity but is
-needed so that the :doc:`minimize <minimize>` command can include the
-forces added by this fix in a consistent manner.  I.e. there is a
-decrease in potential energy when atoms move in the direction of the
-added forces.
+The :doc:`fix_modify <fix_modify>` *energy* option is supported by
+this fix to add the potential "energy" inferred by the added torques
+to the global potential energy of the system as part of
+:doc:`thermodynamic output <thermo_style>`.  The default setting for
+this fix is :doc:`fix_modify energy no <fix_modify>`.  Note that this
+is a fictitious quantity but is needed so that the :doc:`minimize
+<minimize>` command can include the forces added by this fix in a
+consistent manner.  I.e. there is a decrease in potential energy when
+atoms move in the direction of the added forces.
 
 The :doc:`fix_modify <fix_modify>` *respa* option is supported by
 this fix. This allows to set at which level of the :doc:`r-RESPA <run_style>`
@@ -78,16 +80,28 @@ No parameter of this fix can be used with the *start/stop* keywords of
 the :doc:`run <run>` command.
 
 The forces due to this fix are imposed during an energy minimization,
-invoked by the :doc:`minimize <minimize>` command.  You should not
-specify force components with a variable that has time-dependence for
-use with a minimizer, since the minimizer increments the timestep as
-the iteration count during the minimization.
+invoked by the :doc:`minimize <minimize>` command.
+
+.. note::
+
+   If you want the fictitious potential energy associated with the
+   added forces to be included in the total potential energy of the
+   system (the quantity being minimized), you MUST enable the
+   :doc:`fix_modify <fix_modify>` *energy* option for this fix.
+
+.. note::
+
+   You should not specify force components with a variable that has
+   time-dependence for use with a minimizer, since the minimizer
+   increments the timestep as the iteration count during the
+   minimization.
 
 Restrictions
 """"""""""""
 
 This fix is part of the USER-MISC package.  It is only enabled if
-LAMMPS was built with that package.  See the :doc:`Build package <Build_package>` doc page for more info.
+LAMMPS was built with that package.  See the :doc:`Build package
+<Build_package>` doc page for more info.
 
 Related commands
 """"""""""""""""

doc/src/fix_atc.rst

@@ -122,10 +122,22 @@ Restart, fix_modify, output, run start/stop, minimize info
 """""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
 No information about this fix is written to :doc:`binary restart files
-<restart>`.  The :doc:`fix_modify <fix_modify>` options relevant to this
-fix are listed below.  No global scalar or vector or per-atom quantities
-are stored by this fix for access by various :doc:`output commands
-<Howto_output>`.  No parameter of this fix can be used with the
+<restart>`.
+
+The :doc:`fix_modify <fix_modify>` *energy* option is not supported by
+this fix, but this fix does add the kinetic energy imparted to atoms
+by the momentum coupling mode of the AtC package to the global
+potential energy of the system as part of :doc:`thermodynamic output
+<thermo_style>`.
+
+Additional :doc:`fix_modify <fix_modify>` options relevant to this
+fix are listed below.
+
+This fix computes a global scalar which can be accessed by various
+:doc:`output commands <Howto_output>`.  The scalar is the energy
+discussed in the previous paragraph.  The scalar value is "extensive".
+
+No parameter of this fix can be used with the
 *start/stop* keywords of the :doc:`run <run>` command.  This fix is not
 invoked during :doc:`energy minimization <minimize>`.
 
@@ -145,10 +157,10 @@ one, e.g. nve, nvt, etc. In addition, currently:
 Related commands
 """"""""""""""""
 
-After specifying this fix in your input script, several other
-:doc:`fix_modify <fix_modify>` commands are used to setup the problem,
-e.g. define the finite element mesh and prescribe initial and boundary
-conditions.
+After specifying this fix in your input script, several
+:doc:`fix_modify AtC <fix_modify>` commands are used to setup the
+problem, e.g. define the finite element mesh and prescribe initial and
+boundary conditions.  Each of these options has its own doc page.
 
 *fix_modify* commands for setup:
 
@@ -240,7 +252,8 @@ miscellaneous *fix_modify* commands:
 * :doc:`fix_modify AtC remove_species <atc_remove_species>`
 * :doc:`fix_modify AtC remove_molecule <atc_remove_molecule>`
 
-Note: a set of example input files with the attendant material files are included in the ``examples/USER/atc`` folders.
+Note: a set of example input files with the attendant material files
+are included in the ``examples/USER/atc`` folders.
 
 Default
 """""""
@@ -252,30 +265,52 @@ For detailed exposition of the theory and algorithms please see:
 
 .. _Wagner:
 
-**(Wagner)** Wagner, GJ; Jones, RE; Templeton, JA; Parks, MA, "An atomistic-to-continuum coupling method for heat transfer in solids." Special Issue of Computer Methods and Applied Mechanics (2008) 197:3351.
+**(Wagner)** Wagner, GJ; Jones, RE; Templeton, JA; Parks, MA, "An
+ atomistic-to-continuum coupling method for heat transfer in solids."
+ Special Issue of Computer Methods and Applied Mechanics (2008)
+ 197:3351.
 
 .. _Zimmeman2004:
 
-**(Zimmerman2004)** Zimmerman, JA; Webb, EB; Hoyt, JJ;. Jones, RE; Klein, PA; Bammann, DJ, "Calculation of stress in atomistic simulation." Special Issue of Modelling and Simulation in Materials Science and Engineering (2004), 12:S319.
+**(Zimmerman2004)** Zimmerman, JA; Webb, EB; Hoyt, JJ;. Jones, RE;
+ Klein, PA; Bammann, DJ, "Calculation of stress in atomistic
+ simulation." Special Issue of Modelling and Simulation in Materials
+ Science and Engineering (2004), 12:S319.
 
 .. _Zimmerman2010:
 
-**(Zimmerman2010)** Zimmerman, JA; Jones, RE; Templeton, JA, "A material frame approach for evaluating continuum variables in atomistic simulations." Journal of Computational Physics (2010), 229:2364.
+**(Zimmerman2010)** Zimmerman, JA; Jones, RE; Templeton, JA, "A
+ material frame approach for evaluating continuum variables in
+ atomistic simulations." Journal of Computational Physics (2010),
+ 229:2364.
 
 .. _Templeton2010:
 
-**(Templeton2010)** Templeton, JA; Jones, RE; Wagner, GJ, "Application of a field-based method to spatially varying thermal transport problems in molecular dynamics." Modelling and Simulation in Materials Science and Engineering (2010), 18:085007.
+**(Templeton2010)** Templeton, JA; Jones, RE; Wagner, GJ, "Application
+ of a field-based method to spatially varying thermal transport
+ problems in molecular dynamics." Modelling and Simulation in
+ Materials Science and Engineering (2010), 18:085007.
 
 .. _Jones:
 
-**(Jones)** Jones, RE; Templeton, JA; Wagner, GJ; Olmsted, D; Modine, JA, "Electron transport enhanced molecular dynamics for metals and semi-metals." International Journal for Numerical Methods in Engineering (2010), 83:940.
+**(Jones)** Jones, RE; Templeton, JA; Wagner, GJ; Olmsted, D; Modine,
+ JA, "Electron transport enhanced molecular dynamics for metals and
+ semi-metals." International Journal for Numerical Methods in
+ Engineering (2010), 83:940.
 
 .. _Templeton2011:
 
-**(Templeton2011)** Templeton, JA; Jones, RE; Lee, JW; Zimmerman, JA; Wong, BM, "A long-range electric field solver for molecular dynamics based on atomistic-to-continuum modeling." Journal of Chemical Theory and Computation (2011), 7:1736.
+**(Templeton2011)** Templeton, JA; Jones, RE; Lee, JW; Zimmerman, JA;
+ Wong, BM, "A long-range electric field solver for molecular dynamics
+ based on atomistic-to-continuum modeling." Journal of Chemical Theory
+ and Computation (2011), 7:1736.
 
 .. _Mandadapu:
 
-**(Mandadapu)** Mandadapu, KK; Templeton, JA; Lee, JW, "Polarization as a field variable from molecular dynamics simulations." Journal of Chemical Physics (2013), 139:054115.
+**(Mandadapu)** Mandadapu, KK; Templeton, JA; Lee, JW, "Polarization
+ as a field variable from molecular dynamics simulations." Journal of
+ Chemical Physics (2013), 139:054115.
 
-Please refer to the standard finite element (FE) texts, e.g. T.J.R Hughes " The finite element method ", Dover 2003, for the basics of FE simulation.
+Please refer to the standard finite element (FE) texts, e.g. T.J.R
+Hughes " The finite element method ", Dover 2003, for the basics of FE
+simulation.

doc/src/fix_ave_correlate.rst

@@ -93,7 +93,7 @@ from a compute, fix, or variable, then see the :doc:`fix ave/chunk <fix_ave_chun
 :doc:`fix ave/histo <fix_ave_histo>` commands.  If you wish to convert a
 per-atom quantity into a single global value, see the :doc:`compute reduce <compute_reduce>` command.
 
-The input values must either be all scalars.  What kinds of
+The input values must be all scalars.  What kinds of
 correlations between input values are calculated is determined by the
 *type* keyword as discussed below.
 

doc/src/fix_bocs.rst

@@ -75,6 +75,39 @@ Note that *V_avg* and *Coeff_i* should all be in the proper units, e.g. if you
 are using *units real*\ , *V_avg* should be in cubic angstroms, and the
 coefficients should all be in atmospheres \* cubic angstroms.
 
+----------
+
+Restart, fix_modify, output, run start/stop, minimize info
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+This fix writes the cumulative global energy change to :doc:`binary
+restart files <restart>`.  See the :doc:`read_restart <read_restart>`
+command for info on how to re-specify a fix in an input script that
+reads a restart file, so that the fix continues in an uninterrupted
+fashion.
+
+The :doc:`fix_modify <fix_modify>` *temp* option is supported by this
+fix.  You can use it to assign a temperature :doc:`compute <compute>`
+you have defined to this fix which will be used in its thermostatting
+procedure, as described above.  For consistency, the group used by
+this fix and by the compute should be the same.
+
+The cumulative energy change in the system imposed by this fix is
+included in the :doc:`thermodynamic output <thermo_style>` keywords
+*ecouple* and *econserve*.  See the :doc:`thermo_style <thermo_style>`
+doc page for details.
+
+This fix computes a global scalar which can be accessed by various
+:doc:`output commands <Howto_output>`.  The scalar is the same
+cumulative energy change due to this fix described in the previous
+paragraph.  The scalar value calculated by this fix is "extensive".
+
+This fix can ramp its target temperature over multiple runs, using the
+*start* and *stop* keywords of the :doc:`run <run>` command.  See the
+:doc:`run <run>` command for details of how to do this.
+
+This fix is not invoked during :doc:`energy minimization <minimize>`.
+
 Restrictions
 """"""""""""
 

doc/src/fix_bond_react.rst

@@ -35,13 +35,13 @@ Syntax
 * react-ID = user-assigned name for the reaction
 * react-group-ID = only atoms in this group are considered for the reaction
 * Nevery = attempt reaction every this many steps
-* Rmin = bonding pair atoms must be separated by more than Rmin to initiate reaction (distance units)
-* Rmax = bonding pair atoms must be separated by less than Rmax to initiate reaction (distance units)
+* Rmin = initiator atoms must be separated by more than Rmin to initiate reaction (distance units)
+* Rmax = initiator atoms must be separated by less than Rmax to initiate reaction (distance units)
 * template-ID(pre-reacted) = ID of a molecule template containing pre-reaction topology
 * template-ID(post-reacted) = ID of a molecule template containing post-reaction topology
 * map_file = name of file specifying corresponding atom-IDs in the pre- and post-reacted templates
 * zero or more individual keyword/value pairs may be appended to each react argument
-* individual_keyword = *prob* or *max_rxn* or *stabilize_steps* or *custom_charges*
+* individual_keyword = *prob* or *max_rxn* or *stabilize_steps* or *custom_charges* or *molecule* or *modify_create*
 
   .. parsed-literal::
 
@@ -55,6 +55,16 @@ Syntax
          *custom_charges* value = *no* or *fragmentID*
            no = update all atomic charges (default)
            fragmentID = ID of molecule fragment whose charges are updated
+         *molecule* value = *off* or *inter* or *intra*
+           off = allow both inter- and intramolecular reactions (default)
+           inter = search for reactions between molecules with different IDs
+           intra = search for reactions within the same molecule
+         *modify_create* keyword values
+           *fit* value = *all* or *fragmentID*
+             all = use all eligible atoms for create-atoms fit (default)
+             fragmentID = ID of molecule fragment used for create-atoms fit
+           *overlap* value = R
+             R = only insert atom/molecule if further than R from existing particles (distance units)
 
 Examples
 """"""""
@@ -85,7 +95,9 @@ documentation. Topology changes are defined in pre- and post-reaction
 molecule templates and can include creation and deletion of bonds,
 angles, dihedrals, impropers, bond types, angle types, dihedral types,
 atom types, or atomic charges. In addition, reaction by-products or
-other molecules can be identified and deleted.
+other molecules can be identified and deleted. Finally, atoms can be
+created and inserted at specific positions relative to the reaction
+site.
 
 Fix bond/react does not use quantum mechanical (eg. fix qmmm) or
 pairwise bond-order potential (eg. Tersoff or AIREBO) methods to
@@ -172,8 +184,8 @@ timesteps. *Nevery* can be specified with an equal-style
 integer.
 
 Three physical conditions must be met for a reaction to occur. First,
-a bonding atom pair must be identified within the reaction distance
-cutoffs. Second, the topology surrounding the bonding atom pair must
+an initiator atom pair must be identified within the reaction distance
+cutoffs. Second, the topology surrounding the initiator atom pair must
 match the topology of the pre-reaction template. Only atom types and
 bond connectivity are used to identify a valid reaction site (not bond
 types, etc.). Finally, any reaction constraints listed in the map file
@@ -181,10 +193,10 @@ types, etc.). Finally, any reaction constraints listed in the map file
 reaction site is eligible to be modified to match the post-reaction
 template.
 
-A bonding atom pair will be identified if several conditions are met.
-First, a pair of atoms I,J within the specified react-group-ID of type
-itype and jtype must be separated by a distance between *Rmin* and
-*Rmax*\ . *Rmin* and *Rmax* can be specified with equal-style
+An initiator atom pair will be identified if several conditions are
+met. First, a pair of atoms I,J within the specified react-group-ID of
+type itype and jtype must be separated by a distance between *Rmin*
+and *Rmax*\ . *Rmin* and *Rmax* can be specified with equal-style
 :doc:`variables <variable>`. For example, these reaction cutoffs can
 be a function of the reaction conversion using the following commands:
 
@@ -194,20 +206,20 @@ be a function of the reaction conversion using the following commands:
    fix myrxn all bond/react react myrxn1 all 1 0 v_rmax mol1 mol2 map_file.txt
    variable rmax equal 3+f_myrxn[1]/100 # arbitrary function of reaction count
 
-The following criteria are used if multiple candidate bonding atom
-pairs are identified within the cutoff distance: 1) If the bonding
+The following criteria are used if multiple candidate initiator atom
+pairs are identified within the cutoff distance: 1) If the initiator
 atoms in the pre-reaction template are not 1-2 neighbors (i.e. not
 directly bonded) the closest potential partner is chosen. 2)
-Otherwise, if the bonding atoms in the pre-reaction template are 1-2
+Otherwise, if the initiator atoms in the pre-reaction template are 1-2
 neighbors (i.e. directly bonded) the farthest potential partner is
 chosen. 3) Then, if both an atom I and atom J have each other as their
-bonding partners, these two atoms are identified as the bonding atom
-pair of the reaction site. Note that it can be helpful to select
-unique atom types for the bonding atoms: if a bonding atom pair is
-identified, as described in the previous steps, but does not
+initiator partners, these two atoms are identified as the initiator
+atom pair of the reaction site. Note that it can be helpful to select
+unique atom types for the initiator atoms: if an initiator atom pair
+is identified, as described in the previous steps, but does not
 correspond to the same pair specified in the pre-reaction template, an
 otherwise eligible reaction could be prevented from occurring. Once
-this unique bonding atom pair is identified for each reaction, there
+this unique initiator atom pair is identified for each reaction, there
 could be two or more reactions that involve the same atom on the same
 timestep. If this is the case, only one such reaction is permitted to
 occur. This reaction is chosen randomly from all potential reactions
@@ -217,7 +229,7 @@ with user-specified probabilities.
 
 The pre-reacted molecule template is specified by a molecule command.
 This molecule template file contains a sample reaction site and its
-surrounding topology. As described below, the bonding atom pairs of
+surrounding topology. As described below, the initiator atom pairs of
 the pre-reacted template are specified by atom ID in the map file. The
 pre-reacted molecule template should contain as few atoms as possible
 while still completely describing the topology of all atoms affected
@@ -231,18 +243,18 @@ missing topology with respect to the simulation. For example, the
 pre-reacted template may contain an atom that, in the simulation, is
 currently connected to the rest of a long polymer chain. These are
 referred to as edge atoms, and are also specified in the map file. All
-pre-reaction template atoms should be linked to a bonding atom, via at
-least one path that does not involve edge atoms. When the pre-reaction
-template contains edge atoms, not all atoms, bonds, charges, etc.
-specified in the reaction templates will be updated. Specifically,
-topology that involves only atoms that are 'too near' to template
-edges will not be updated. The definition of 'too near the edge'
-depends on which interactions are defined in the simulation. If the
-simulation has defined dihedrals, atoms within two bonds of edge atoms
-are considered 'too near the edge.' If the simulation defines angles,
-but not dihedrals, atoms within one bond of edge atoms are considered
-'too near the edge.' If just bonds are defined, only edge atoms are
-considered 'too near the edge.'
+pre-reaction template atoms should be linked to an initiator atom, via
+at least one path that does not involve edge atoms. When the
+pre-reaction template contains edge atoms, not all atoms, bonds,
+charges, etc. specified in the reaction templates will be updated.
+Specifically, topology that involves only atoms that are 'too near' to
+template edges will not be updated. The definition of 'too near the
+edge' depends on which interactions are defined in the simulation. If
+the simulation has defined dihedrals, atoms within two bonds of edge
+atoms are considered 'too near the edge.' If the simulation defines
+angles, but not dihedrals, atoms within one bond of edge atoms are
+considered 'too near the edge.' If just bonds are defined, only edge
+atoms are considered 'too near the edge.'
 
 .. note::
 
@@ -258,14 +270,14 @@ command page.
 
 The post-reacted molecule template contains a sample of the reaction
 site and its surrounding topology after the reaction has occurred. It
-must contain the same number of atoms as the pre-reacted template. A
-one-to-one correspondence between the atom IDs in the pre- and
-post-reacted templates is specified in the map file as described
-below. Note that during a reaction, an atom, bond, etc. type may
-change to one that was previously not present in the simulation. These
-new types must also be defined during the setup of a given simulation.
-A discussion of correctly handling this is also provided on the
-:doc:`molecule <molecule>` command page.
+must contain the same number of atoms as the pre-reacted template
+(unless there are created atoms). A one-to-one correspondence between
+the atom IDs in the pre- and post-reacted templates is specified in
+the map file as described below. Note that during a reaction, an atom,
+bond, etc. type may change to one that was previously not present in
+the simulation. These new types must also be defined during the setup
+of a given simulation. A discussion of correctly handling this is also
+provided on the :doc:`molecule <molecule>` command page.
 
 .. note::
 
@@ -279,7 +291,7 @@ A discussion of correctly handling this is also provided on the
 The map file is a text document with the following format:
 
 A map file has a header and a body. The header of map file the
-contains one mandatory keyword and four optional keywords. The
+contains one mandatory keyword and five optional keywords. The
 mandatory keyword is 'equivalences':
 
 .. parsed-literal::
@@ -292,29 +304,32 @@ The optional keywords are 'edgeIDs', 'deleteIDs', 'chiralIDs' and
 .. parsed-literal::
 
    N *edgeIDs* = # of edge atoms N in the pre-reacted molecule template
-   N *deleteIDs* = # of atoms N that are specified for deletion
-   N *chiralIDs* = # of specified chiral centers N
-   N *constraints* = # of specified reaction constraints N
+   N *deleteIDs* = # of atoms N that are deleted
+   N *createIDs* = # of atoms N that are created
+   N *chiralIDs* = # of chiral centers N
+   N *constraints* = # of reaction constraints N
 
-The body of the map file contains two mandatory sections and four
+The body of the map file contains two mandatory sections and five
 optional sections. The first mandatory section begins with the keyword
-'BondingIDs' and lists the atom IDs of the bonding atom pair in the
-pre-reacted molecule template. The second mandatory section begins
-with the keyword 'Equivalences' and lists a one-to-one correspondence
-between atom IDs of the pre- and post-reacted templates. The first
-column is an atom ID of the pre-reacted molecule template, and the
-second column is the corresponding atom ID of the post-reacted
-molecule template. The first optional section begins with the keyword
-'EdgeIDs' and lists the atom IDs of edge atoms in the pre-reacted
-molecule template. The second optional section begins with the keyword
-'DeleteIDs' and lists the atom IDs of pre-reaction template atoms to
-delete. The third optional section begins with the keyword 'ChiralIDs'
-lists the atom IDs of chiral atoms whose handedness should be
-enforced. The fourth optional section begins with the keyword
-'Constraints' and lists additional criteria that must be satisfied in
-order for the reaction to occur. Currently, there are five types of
-constraints available, as discussed below: 'distance', 'angle',
-'dihedral', 'arrhenius', and 'rmsd'.
+'InitiatorIDs' and lists the two atom IDs of the initiator atom pair
+in the pre-reacted molecule template. The second mandatory section
+begins with the keyword 'Equivalences' and lists a one-to-one
+correspondence between atom IDs of the pre- and post-reacted
+templates. The first column is an atom ID of the pre-reacted molecule
+template, and the second column is the corresponding atom ID of the
+post-reacted molecule template. The first optional section begins with
+the keyword 'EdgeIDs' and lists the atom IDs of edge atoms in the
+pre-reacted molecule template. The second optional section begins with
+the keyword 'DeleteIDs' and lists the atom IDs of pre-reaction
+template atoms to delete. The third optional section begins with the
+keyword 'CreateIDs' and lists the atom IDs of the post-reaction
+template atoms to create. The fourth optional section begins with the
+keyword 'ChiralIDs' lists the atom IDs of chiral atoms whose
+handedness should be enforced. The fifth optional section begins with
+the keyword 'Constraints' and lists additional criteria that must be
+satisfied in order for the reaction to occur. Currently, there are
+five types of constraints available, as discussed below: 'distance',
+'angle', 'dihedral', 'arrhenius', and 'rmsd'.
 
 A sample map file is given below:
 
@@ -327,7 +342,7 @@ A sample map file is given below:
    7 equivalences
    2 edgeIDs
 
-   BondingIDs
+   InitiatorIDs
 
    3
    5
@@ -349,6 +364,38 @@ A sample map file is given below:
 
 ----------
 
+A user-specified set of atoms can be deleted by listing their
+pre-reaction template IDs in the DeleteIDs section. A deleted atom
+must still be included in the post-reaction molecule template, in
+which it cannot be bonded to an atom that is not deleted. In addition
+to deleting unwanted reaction by-products, this feature can be used to
+remove specific topologies, such as small rings, that may be otherwise
+indistinguishable.
+
+Atoms can be created by listing their post-reaction template IDs in
+the CreateIDs section. A created atom should not be included in the
+pre-reaction template. The inserted positions of created atoms are
+determined by the coordinates of the post-reaction template, after
+optimal translation and rotation of the post-reaction template to the
+reaction site (using a fit with atoms that are neither created nor
+deleted). The *modify_create* keyword can be used to modify the
+default behavior when creating atoms. The *modify_create* keyword has
+two sub-keywords, *fit* and *overlap*. One or more of the sub-keywords
+may be used after the *modify_create* keyword. The *fit* sub-keyword
+can be used to specify which post-reaction atoms are used for the
+optimal translation and rotation of the post-reaction template. The
+*fragmentID* value of the *fit* sub-keyword must be the name of a
+molecule fragment defined in the post-reaction :doc:`molecule
+<molecule>` template, and only atoms in this fragment are used for the
+fit. Atoms are created only if no current atom in the simulation is
+within a distance R of any created atom, including the effect of
+periodic boundary conditions if applicable. R is defined by the
+*overlap* sub-keyword. Note that the default value for R is 0.0, which
+will allow atoms to strongly overlap if you are inserting where other
+atoms are present. The velocity of each created atom is initialized in
+a random direction with a magnitude calculated from the instantaneous
+temperature of the reaction site.
+
 The handedness of atoms that are chiral centers can be enforced by
 listing their IDs in the ChiralIDs section. A chiral atom must be
 bonded to four atoms with mutually different atom types. This feature
@@ -453,6 +500,23 @@ example, the molecule fragment could consist of only the backbone
 atoms of a polymer chain. This constraint can be used to enforce a
 specific relative position and orientation between reacting molecules.
 
+By default, all constraints must be satisfied for the reaction to
+occur. In other words, constraints are evaluated as a series of
+logical values using the logical AND operator "&&". More complex logic
+can be achieved by explicitly adding the logical AND operator "&&" or
+the logical OR operator "||" after a given constraint command. If a
+logical operator is specified after a constraint, it must be placed
+after all constraint parameters, on the same line as the constraint
+(one per line). Similarly, parentheses can be used to group
+constraints. The expression that results from concatenating all
+constraints should be a valid logical expression that can be read by
+the :doc:`variable <variable>` command after converting each
+constraint to a logical value. Because exactly one constraint is
+allowed per line, having a valid logical expression implies that left
+parentheses "(" should only appear before a constraint, and right
+parentheses ")" should only appear after a constraint and before any
+logical operator.
+
 Once a reaction site has been successfully identified, data structures
 within LAMMPS that store bond topology are updated to reflect the
 post-reacted molecule template. All force fields with fixed bonds,
@@ -462,7 +526,7 @@ A few capabilities to note: 1) You may specify as many *react*
 arguments as desired. For example, you could break down a complicated
 reaction mechanism into several reaction steps, each defined by its
 own *react* argument. 2) While typically a bond is formed or removed
-between the bonding atom pairs specified in the pre-reacted molecule
+between the initiator atoms specified in the pre-reacted molecule
 template, this is not required. 3) By reversing the order of the pre-
 and post- reacted molecule templates in another *react* argument, you
 can allow for the possibility of one or more reverse reactions.
@@ -491,22 +555,21 @@ situations, decreasing rather than increasing this parameter will
 result in an increase in stability.
 
 The *custom_charges* keyword can be used to specify which atoms'
-atomic charges are updated. When the value is set to 'no,' all atomic
+atomic charges are updated. When the value is set to 'no', all atomic
 charges are updated to those specified by the post-reaction template
 (default). Otherwise, the value should be the name of a molecule
 fragment defined in the pre-reaction molecule template. In this case,
 only the atomic charges of atoms in the molecule fragment are updated.
 
-A few other considerations:
+The *molecule* keyword can be used to force the reaction to be
+intermolecular, intramolecular or either. When the value is set to
+'off', molecule IDs are not considered when searching for reactions
+(default). When the value is set to 'inter', the initiator atoms must
+have different molecule IDs in order to be considered for the
+reaction. When the value is set to 'intra', only initiator atoms with
+the same molecule ID are considered for the reaction.
 
-Many reactions result in one or more atoms that are considered
-unwanted by-products. Therefore, bond/react provides the option to
-delete a user-specified set of atoms. These pre-reaction atoms are
-identified in the map file. A deleted atom must still be included in
-the post-reaction molecule template, in which it cannot be bonded to
-an atom that is not deleted. In addition to deleting unwanted reaction
-by-products, this feature can be used to remove specific topologies,
-such as small rings, that may be otherwise indistinguishable.
+A few other considerations:
 
 Optionally, you can enforce additional behaviors on reacting atoms.
 For example, it may be beneficial to force reacting atoms to remain at
@@ -558,7 +621,7 @@ These is 1 quantity for each react argument:
 No parameter of this fix can be used with the *start/stop* keywords
 of the :doc:`run <run>` command.  This fix is not invoked during :doc:`energy minimization <minimize>`.
 
-When fix bond/react is 'unfixed,' all internally-created groups are
+When fix bond/react is 'unfixed', all internally-created groups are
 deleted. Therefore, fix bond/react can only be unfixed after unfixing
 all other fixes that use any group created by fix bond/react.
 
@@ -581,10 +644,14 @@ Default
 """""""
 
 The option defaults are stabilization = no, prob = 1.0, stabilize_steps = 60,
-reset_mol_ids = yes, custom_charges = no
+reset_mol_ids = yes, custom_charges = no, molecule = off, modify_create = no
 
 ----------
 
 .. _Gissinger:
 
-**(Gissinger)** Gissinger, Jensen and Wise, Polymer, 128, 211 (2017).
+**(Gissinger2017)** Gissinger, Jensen and Wise, Polymer, 128, 211-217 (2017).
+
+.. _Gissinger2020:
+
+**(Gissinger2020)** Gissinger, Jensen and Wise, Macromolecules, 53, 22, 9953-9961 (2020).

doc/src/fix_client_md.rst

@@ -47,14 +47,15 @@ for running *ab initio* MD with quantum forces.
 The group associated with this fix is ignored.
 
 The protocol and :doc:`units <units>` for message format and content
-that LAMMPS exchanges with the server code is defined on the :doc:`server md <server_md>` doc page.
+that LAMMPS exchanges with the server code is defined on the
+:doc:`server md <server_md>` doc page.
 
 Note that when using LAMMPS as an MD client, your LAMMPS input script
 should not normally contain force field commands, like a
 :doc:`pair_style <pair_style>`, :doc:`bond_style <bond_style>`, or
-:doc:`kspace_style <kspace_style>` command.  However it is possible for
-a server code to only compute a portion of the full force-field, while
-LAMMPS computes the remaining part.  Your LAMMPS script can also
+:doc:`kspace_style <kspace_style>` command.  However it is possible
+for a server code to only compute a portion of the full force-field,
+while LAMMPS computes the remaining part.  Your LAMMPS script can also
 specify boundary conditions or force constraints in the usual way,
 which will be added to the per-atom forces returned by the server
 code.
@@ -69,16 +70,21 @@ LAMMPS and another code in tandem to perform a coupled simulation.
 Restart, fix_modify, output, run start/stop, minimize info
 """""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
-No information about this fix is written to :doc:`binary restart files <restart>`.
+No information about this fix is written to :doc:`binary restart files
+<restart>`.
 
-The :doc:`fix_modify <fix_modify>` *energy* option is supported by this
-fix to add the potential energy computed by the server application to
-the system's potential energy as part of :doc:`thermodynamic output <thermo_style>`.
+The :doc:`fix_modify <fix_modify>` *energy* option is supported by
+this fix to add the potential energy set by the server application to
+the global potential energy of the system as part of
+:doc:`thermodynamic output <thermo_style>`.  The default setting for
+this fix is :doc:`fix_modify energy yes <fix_modify>`.
 
-The :doc:`fix_modify <fix_modify>` *virial* option is supported by this
-fix to add the server application's contribution to the system's
-virial as part of :doc:`thermodynamic output <thermo_style>`.  The
-default is *virial yes*
+The :doc:`fix_modify <fix_modify>` *virial* option is supported by
+this fix to add the contribution computed by the server application to
+the global pressure of the system via the :doc:`compute pressure
+<compute_pressure>` command.  This can be accessed by
+:doc:`thermodynamic output <thermo_style>`.  The default setting for
+this fix is :doc:`fix_modify virial yes <fix_modify>`.
 
 This fix computes a global scalar which can be accessed by various
 :doc:`output commands <Howto_output>`.  The scalar is the potential
@@ -86,13 +92,16 @@ energy discussed above.  The scalar value calculated by this fix is
 "extensive".
 
 No parameter of this fix can be used with the *start/stop* keywords of
-the :doc:`run <run>` command.  This fix is not invoked during :doc:`energy minimization <minimize>`.
+the :doc:`run <run>` command.
+
+This fix is not invoked during :doc:`energy minimization <minimize>`.
 
 Restrictions
 """"""""""""
 
 This fix is part of the MESSAGE package.  It is only enabled if LAMMPS
-was built with that package.  See the :doc:`Build package <Build_package>` doc page for more info.
+was built with that package.  See the :doc:`Build package
+<Build_package>` doc page for more info.
 
 A script that uses this command must also use the
 :doc:`message <message>` command to setup and shut down the messaging

doc/src/fix_cmap.rst

@@ -29,11 +29,12 @@ Description
 This command enables CMAP cross-terms to be added to simulations which
 use the CHARMM force field.  These are relevant for any CHARMM model
 of a peptide or protein sequences that is 3 or more amino-acid
-residues long; see :ref:`(Buck) <Buck>` and :ref:`(Brooks) <Brooks2>` for details,
-including the analytic energy expressions for CMAP interactions.  The
-CMAP cross-terms add additional potential energy contributions to pairs
-of overlapping phi-psi dihedrals of amino-acids, which are important
-to properly represent their conformational behavior.
+residues long; see :ref:`(Buck) <Buck>` and :ref:`(Brooks) <Brooks2>`
+for details, including the analytic energy expressions for CMAP
+interactions.  The CMAP cross-terms add additional potential energy
+contributions to pairs of overlapping phi-psi dihedrals of
+amino-acids, which are important to properly represent their
+conformational behavior.
 
 The examples/cmap directory has a sample input script and data file
 for a small peptide, that illustrates use of the fix cmap command.
@@ -93,19 +94,27 @@ the note below about how to include the CMAP energy when performing an
 Restart, fix_modify, output, run start/stop, minimize info
 """""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
-This fix writes the list of CMAP cross-terms to :doc:`binary restart files <restart>`.  See the :doc:`read_restart <read_restart>` command
+This fix writes the list of CMAP cross-terms to :doc:`binary restart
+files <restart>`.  See the :doc:`read_restart <read_restart>` command
 for info on how to re-specify a fix in an input script that reads a
 restart file, so that the operation of the fix continues in an
 uninterrupted fashion.
 
-The :doc:`fix_modify <fix_modify>` *energy* option is supported by this
-fix to add the potential "energy" of the CMAP interactions system's
-potential energy as part of :doc:`thermodynamic output <thermo_style>`.
+The :doc:`fix_modify <fix_modify>` *energy* option is supported by
+this fix to add the potential energy of the CMAP interactions to both
+the global potential energy and peratom potential energies of the
+system as part of :doc:`thermodynamic output <thermo_style>` or
+output by the :doc:`compute pe/atom <compute_pe_atom>` command.  The
+default setting for this fix is :doc:`fix_modify energy yes
+<fix_modify>`.
 
-The :doc:`fix_modify <fix_modify>` *virial* option is supported by this
-fix to add the contribution due to the interaction between atoms to
-the system's virial as part of :doc:`thermodynamic output <thermo_style>`.
-The default is *virial yes*
+The :doc:`fix_modify <fix_modify>` *virial* option is supported by
+this fix to add the contribution due to the CMAP interactions to both
+the global pressure and per-atom stress of the system via the
+:doc:`compute pressure <compute_pressure>` and :doc:`compute
+stress/atom <compute_stress_atom>` commands.  The former can be
+accessed by :doc:`thermodynamic output <thermo_style>`.  The default
+setting for this fix is :doc:`fix_modify virial yes <fix_modify>`.
 
 This fix computes a global scalar which can be accessed by various
 :doc:`output commands <Howto_output>`.  The scalar is the potential
@@ -121,8 +130,8 @@ invoked by the :doc:`minimize <minimize>` command.
 .. note::
 
    If you want the potential energy associated with the CMAP terms
-   forces to be included in the total potential energy of the system (the
-   quantity being minimized), you MUST enable the
+   forces to be included in the total potential energy of the system
+   (the quantity being minimized), you MUST not disable the
    :doc:`fix_modify <fix_modify>` *energy* option for this fix.
 
 Restrictions