Merge pull request #2414 from akohlmey/next_lammps_version

Update version strings for next patch release

.github/CODEOWNERS

@@ -114,6 +114,7 @@ src/info.*                @akohlmey @rbberger
 src/timer.*               @akohlmey
 src/min*                  @sjplimp @stanmoore1
 src/utils.*               @akohlmey @rbberger
+src/math_eigen_impl.h     @jewettaij
 
 # tools
 tools/msi2lmp/*       @akohlmey
@@ -134,6 +135,9 @@ cmake/presets/*.cmake @junghans @rbberger @akohlmey
 # python
 python/*              @rbberger
 
+# fortran
+fortran/*             @akohlmey
+
 # docs
 doc/utils/*/*         @rbberger
 doc/Makefile          @rbberger

.github/CONTRIBUTING.md

@@ -67,6 +67,7 @@ How quickly your contribution will be integrated depends largely on how much eff
 
 Here is a checklist of steps you need to follow to submit a single file or user package for our consideration. Following these steps will save both you and us time. See existing files in packages in the source directory for examples. If you are uncertain, please ask on the lammps-users mailing list.
 
+* C++ source code must be compatible with the C++-11 standard. Packages may require a later standard, if justified.
 * All source files you provide must compile with the most current version of LAMMPS with multiple configurations. In particular you need to test compiling LAMMPS from scratch with `-DLAMMPS_BIGBIG` set in addition to the default `-DLAMMPS_SMALLBIG` setting. Your code will need to work correctly in serial and in parallel using MPI.
 * For consistency with the rest of LAMMPS and especially, if you want your contribution(s) to be added to main LAMMPS code or one of its standard packages, it needs to be written in a style compatible with other LAMMPS source files. This means: 2-character indentation per level, no tabs, no trailing whitespace, no lines over 80 characters. I/O is done via the C-style stdio library, style class header files should not import any system headers, STL containers should be avoided in headers, and forward declarations used where possible or needed. All added code should be placed into the LAMMPS_NS namespace or a sub-namespace; global or static variables should be avoided, as they conflict with the modular nature of LAMMPS and the C++ class structure. There MUST NOT be any "using namespace XXX;" statements in headers. In the implementation file (<name>.cpp) system includes should be placed in angular brackets (<>) and for c-library functions the C++ style header files should be included (<cstdio> instead of <stdio.h>, or <cstring> instead of <string.h>). This all is so the developers can more easily understand, integrate, and maintain your contribution and reduce conflicts with other parts of LAMMPS. This basically means that the code accesses data structures, performs its operations, and is formatted similar to other LAMMPS source files, including the use of the error class for error and warning messages.
 * Source, style name, and documentation file should follow the following naming convention: style names should be lowercase and words separated by a forward slash; for a new fix style 'foo/bar', the class should be named FixFooBar, the name of the source files should be 'fix_foo_bar.h' and 'fix_foo_bar.cpp' and the corresponding documentation should be in a file 'fix_foo_bar.rst'.

.github/PULL_REQUEST_TEMPLATE.md

@@ -2,7 +2,7 @@
 
 <!--Briefly describe the new feature(s), enhancement(s), or bugfix(es) included in this pull request.-->
 
-**Related Issues**
+**Related Issue(s)**
 
 <!--If this addresses an open GitHub issue for this project, please mention the issue number here, and describe the relation. Use the phrases `fixes #221` or `closes #135`, when you want an issue to be automatically closed when the pull request is merged-->
 

.github/PULL_REQUEST_TEMPLATE/bug_fix.md

@@ -9,34 +9,37 @@ assignees: ''
 
 **Summary**
 
-<!--Briefly describe the bug or bugs, that are eliminated by this pull request.-->
+<!--Briefly describe the bug(s) that are eliminated by this pull request.-->
 
 **Related Issue(s)**
 
-<!--If this request addresses or is related to an existing (open) GitHub issue, e.g. a bug report, mention the issue number number here following a pound sign (aka hashmark), e.g.`#222`.-->
+<!--If this addresses an open GitHub issue for this project, please mention the issue number here, and describe the relation. Use the phrases `fixes #221` or `closes #135`, when you want an issue to be automatically closed when the pull request is merged-->
 
 **Author(s)**
 
-<!--Please state name and affiliation of the author or authors that should be credited with the changes in this pull request-->
+<!--Please state name and affiliation of the author or authors that should be credited with the changes in this pull request. If this pull request adds new files to the distribution, please also provide a suitable "long-lived" e-mail address (ideally something that can outlive your institution's e-mail, in case you change jobs) for the *corresponding* author, i.e. the person the LAMMPS developers can contact directly with questions and requests related to maintenance and support of this contributed code.-->
 
 **Licensing**
 
-By submitting this pull request I implicitly accept, that my submission is subject to the same licensing terms as the files that are modified.
+By submitting this pull request, I agree, that my contribution will be included in LAMMPS and redistributed under either the GNU General Public License version 2 (GPL v2) or the GNU Lesser General Public License version 2.1 (LGPL v2.1).
 
 **Backward Compatibility**
 
-<!--Please state whether any changes in the pull request break backward compatibility for inputs, and - if yes - explain what has been changed and why-->
+<!--Please state whether any changes in the pull request will break backward compatibility for inputs, and - if yes - explain what has been changed and why-->
 
 **Detailed Description**
 
 <!--Provide any relevant details about how the fixed bug can be reproduced, how the changes are implemented, how correctness was verified, how other features - if any - in LAMMPS are affected-->
 
-## Post Submission Checklist
+**Post Submission Checklist**
 
-<!--Please check the fields below as they are completed *after* the pull request is submitted-->
-- [ ] The code in this pull request is complete
+<!--Please check the fields below as they are completed **after** the pull request has been submitted. Delete lines that don't apply-->
+
+- [ ] The feature or features in this pull request is complete
+- [ ] Licensing information is complete
+- [ ] Corresponding author information is complete
 - [ ] The source code follows the LAMMPS formatting guidelines
+- [ ] The feature has been verified to work with the conventional build system
+- [ ] The feature has been verified to work with the CMake based build system
+- [ ] Suitable tests have been added to the unittest tree.
 
-## Further Information, Files, and Links
-
-<!--Put any additional information here, attach relevant text or image files, and URLs to external sites (e.g. to download input decks for testing)-->

.github/PULL_REQUEST_TEMPLATE/maintenance_refactoring.md

@@ -13,23 +13,31 @@ assignees: ''
 
 **Related Issue(s)**
 
-<!--If this request addresses or is related to an existing (open) GitHub issue, e.g. a bug report, mention the issue number number here following a pound sign (aka hashmark), e.g.`#222`.
+<!--If this addresses an open GitHub issue for this project, please mention the issue number here, and describe the relation. Use the phrases `fixes #221` or `closes #135`, when you want an issue to be automatically closed when the pull request is merged-->
 
 **Author(s)**
 
-<!--Please state name and affiliation of the author or authors that should be credited with the changes in this pull request-->
+<!--Please state name and affiliation of the author or authors that should be credited with the changes in this pull request. If this pull request adds new files to the distribution, please also provide a suitable "long-lived" e-mail address (ideally something that can outlive your institution's e-mail, in case you change jobs) for the *corresponding* author, i.e. the person the LAMMPS developers can contact directly with questions and requests related to maintenance and support of this contributed code.-->
 
 **Licensing**
 
-By submitting this pull request I implicitly accept, that my submission is subject to the same licensing terms as the files that are modified.
+By submitting this pull request, I agree, that my contribution will be included in LAMMPS and redistributed under either the GNU General Public License version 2 (GPL v2) or the GNU Lesser General Public License version 2.1 (LGPL v2.1).
+
+**Backward Compatibility**
+
+<!--Please state whether any changes in the pull request will break backward compatibility for inputs, and - if yes - explain what has been changed and why-->
 
 **Detailed Description**
 
-<!--Provide any relevant details about the included changes.-->
+<!--Provide any relevant details about how the changes are implemented, how correctness was verified, how other features - if any - in LAMMPS are affected-->
 
-## Post Submission Checklist
+**Post Submission Checklist**
 
 <!--Please check the fields below as they are completed *after* the pull request is submitted-->
 - [ ] The pull request is complete
 - [ ] The source code follows the LAMMPS formatting guidelines
+- [ ] The feature has been verified to work with the conventional build system
+- [ ] The feature has been verified to work with the CMake based build system
+- [ ] Suitable tests have been added to the unittest tree.
+
 

.github/PULL_REQUEST_TEMPLATE/new_feature.md

@@ -11,32 +11,29 @@ assignees: ''
 
 <!--Briefly describe the new feature(s) included in this pull request.-->
 
-**Related Issues**
+**Related Issue(s)**
 
-<!--If this addresses an existing (open) GitHub issue, e.g. a feature request, mention the issue number here following a pound sign (aka hashmark), e.g. `#331`.-->
+<!--If this addresses an open GitHub issue for this project, please mention the issue number here, and describe the relation. Use the phrases `fixes #221` or `closes #135`, when you want an issue to be automatically closed when the pull request is merged-->
 
 **Author(s)**
 
-<!--Please state name and affiliation of the author or authors that should be credited with the features added in this pull request. Please provide a suitable "long-lived" e-mail address (e.g. from gmail, yahoo, outlook, etc.) for the *corresponding* author, i.e. the person the LAMMPS developers can contact directly with questions and requests related to maintenance and support of this code. now and in the future-->
+<!--Please state name and affiliation of the author or authors that should be credited with the changes in this pull request. If this pull request adds new files to the distribution, please also provide a suitable "long-lived" e-mail address (ideally something that can outlive your institution's e-mail, in case you change jobs) for the *corresponding* author, i.e. the person the LAMMPS developers can contact directly with questions and requests related to maintenance and support of this contributed code.-->
 
 **Licensing**
 
-<!--Please add *yes* or *no* to the following two statements (please contact @lammps/core if you have questions about this)-->
-
-My contribution may be licensed as GPL v2 (default LAMMPS license):
-My contribution may be licensed as LGPL (for use as a library with proprietary software):
+By submitting this pull request, I agree, that my contribution will be included in LAMMPS and redistributed under either the GNU General Public License version 2 (GPL v2) or the GNU Lesser General Public License version 2.1 (LGPL v2.1).
 
 **Backward Compatibility**
 
-<!--Please state if any of the changes in this pull request will affect backward compatibility for inputs, and - if yes - explain what has been changed and why-->
+<!--Please state whether any changes in the pull request will break backward compatibility for inputs, and - if yes - explain what has been changed and why-->
 
 **Implementation Notes**
 
-<!--Provide any relevant details about how the new features are implemented, how correctness was verified, what platforms (OS, compiler, MPI, hardware, number of processors, accelerator(s)) it was tested on-->
+<!--Provide any relevant details about how the new feature(s) are implemented, how correctness was verified, how other features - if any - in LAMMPS are affected-->
 
-## Post Submission Checklist
+**Post Submission Checklist**
 
-<!--Please check the fields below as they are completed *after* the pull request has been submitted-->
+<!--Please check the fields below as they are completed **after** the pull request has been submitted. Delete lines that don't apply-->
 
 - [ ] The feature or features in this pull request is complete
 - [ ] Licensing information is complete
@@ -46,10 +43,11 @@ My contribution may be licensed as LGPL (for use as a library with proprietary s
 - [ ] The added/updated documentation is integrated and tested with the documentation build system
 - [ ] The feature has been verified to work with the conventional build system
 - [ ] The feature has been verified to work with the CMake based build system
+- [ ] Suitable tests have been added to the unittest tree.
 - [ ] A package specific README file has been included or updated
 - [ ] One or more example input decks are included
 
-## Further Information, Files, and Links
+**Further Information, Files, and Links**
 
 <!--Put any additional information here, attach relevant text or image files, and URLs to external sites (e.g. DOIs or webpages)-->
 

.github/PULL_REQUEST_TEMPLATE/update_enhancement.md

@@ -11,17 +11,21 @@ assignees: ''
 
 <!--Briefly describe what kind of updates or enhancements for a package or feature are included. If you are not the original author of the package or feature, please mention, whether your contribution was created independently or in collaboration/cooperation with the original author.-->
 
+**Related Issue(s)**
+
+<!--If this addresses an open GitHub issue for this project, please mention the issue number here, and describe the relation. Use the phrases `fixes #221` or `closes #135`, when you want an issue to be automatically closed when the pull request is merged-->
+
 **Author(s)**
 
 <!--Please state name and affiliation of the author or authors that should be credited with the changes in this pull request-->
 
 **Licensing**
 
-By submitting this pull request I implicitly accept, that my submission is subject to the same licensing terms as the original package or feature(s) that are updated or amended by this pull request.
+By submitting this pull request, I agree, that my contribution will be included in LAMMPS and redistributed under either the GNU General Public License version 2 (GPL v2) or the GNU Lesser General Public License version 2.1 (LGPL v2.1).
 
 **Backward Compatibility**
 
-<!--Please state whether any changes in the pull request break backward compatibility for inputs, and - if yes - explain what has been changed and why-->
+<!--Please state whether any changes in the pull request will break backward compatibility for inputs, and - if yes - explain what has been changed and why-->
 
 **Implementation Notes**
 
@@ -29,11 +33,19 @@ By submitting this pull request I implicitly accept, that my submission is subje
 
 **Post Submission Checklist**
 
-<!--Please check the fields below as they are completed-->
+<!--Please check the fields below as they are completed **after** the pull request has been submitted. Delete lines that don't apply-->
+
 - [ ] The feature or features in this pull request is complete
-- [ ] Suitable updates to the existing docs are included
-- [ ] One or more example input decks are included
+- [ ] Licensing information is complete
+- [ ] Corresponding author information is complete
 - [ ] The source code follows the LAMMPS formatting guidelines
+- [ ] Suitable updates to the existing docs are included
+- [ ] The updated documentation is integrated and tested with the documentation build system
+- [ ] The feature has been verified to work with the conventional build system
+- [ ] The feature has been verified to work with the CMake based build system
+- [ ] Suitable tests have been updated or added to the unittest tree.
+- [ ] A package specific README file has been updated
+- [ ] One or more example input decks are included
 
 **Further Information, Files, and Links**
 

.gitignore

@@ -37,6 +37,7 @@ vgcore.*
 ehthumbs.db
 Thumbs.db
 .clang-format
+.lammps_history
 
 #cmake
 /build*

README

@@ -22,28 +22,32 @@ more information about the code and its uses.
 
 The LAMMPS distribution includes the following files and directories:
 
-README			   this file
-LICENSE			   the GNU General Public License (GPL)
-bench			   benchmark problems
-cmake			   CMake build system
-doc			   documentation
-examples		   simple test problems
-lib			   libraries LAMMPS can be linked with
-potentials		   interatomic potential files
-python			   Python wrapper on LAMMPS as a library
-src			   source files
-tools			   pre- and post-processing tools
+README                     this file
+LICENSE                    the GNU General Public License (GPL)
+bench                      benchmark problems
+cmake                      CMake build files
+doc                        documentation
+examples                   simple test problems
+fortran                    Fortran wrapper for LAMMPS
+lib                        additional provided or external libraries
+potentials                 interatomic potential files
+python                     Python wrappers for LAMMPS
+src                        source files
+tools                      pre- and post-processing tools
 
 Point your browser at any of these files to get started:
 
-http://lammps.sandia.gov/doc/Manual.html         the LAMMPS manual
-http://lammps.sandia.gov/doc/Intro.html          hi-level introduction
-http://lammps.sandia.gov/doc/Build.html          how to build LAMMPS
-http://lammps.sandia.gov/doc/Run_head.html       how to run LAMMPS
-http://lammps.sandia.gov/doc/Developer.pdf       LAMMPS developer guide
+https://lammps.sandia.gov/doc/Manual.html         LAMMPS user 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/Modify.html         how to modify and extend LAMMPS
+https://lammps.sandia.gov/doc/pg_developer.html   LAMMPS developer guide
 
 You can also create these doc pages locally:
 
 % cd doc
 % make html                # creates HTML pages in doc/html
-% make pdf                 # creates Manual.pdf and Developer.pdf
+% make pdf                 # creates Manual.pdf

cmake/CMakeLists.txt

@@ -90,6 +90,7 @@ if(BUILD_SHARED_LIBS) # for all pkg libs, mpi_stubs and linalg
 endif()
 
 option(BUILD_TOOLS "Build and install LAMMPS tools (msi2lmp, binary2txt, chain)" OFF)
+option(BUILD_LAMMPS_SHELL "Build and install the LAMMPS shell" OFF)
 
 include(GNUInstallDirs)
 file(GLOB ALL_SOURCES ${LAMMPS_SOURCE_DIR}/[^.]*.cpp)
@@ -157,11 +158,11 @@ else()
   file(GLOB MPI_SOURCES ${LAMMPS_SOURCE_DIR}/STUBS/mpi.c)
   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> $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}/lammps/mpi>)
-  install(FILES ${LAMMPS_SOURCE_DIR}/STUBS/mpi.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/lammps/mpi)
+  target_include_directories(mpi_stubs PUBLIC $<BUILD_INTERFACE:${LAMMPS_SOURCE_DIR}/STUBS>)
   if(BUILD_SHARED_LIBS)
     target_link_libraries(lammps PRIVATE mpi_stubs)
-    target_include_directories(lammps INTERFACE $<BUILD_INTERFACE:${LAMMPS_SOURCE_DIR}/STUBS> $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}/lammps/mpi>)
+    target_include_directories(lammps INTERFACE $<BUILD_INTERFACE:${LAMMPS_SOURCE_DIR}/STUBS>)
+    target_compile_definitions(lammps INTERFACE $<INSTALL_INTERFACE:LAMMPS_LIB_NO_MPI>)
   else()
     target_link_libraries(lammps PUBLIC mpi_stubs)
   endif()
@@ -218,10 +219,9 @@ if(BUILD_OMP)
     message(FATAL_ERROR "Cannot find the 'omp.h' header file required for full OpenMP support")
   endif()
 
-  if (((CMAKE_CXX_COMPILER_ID STREQUAL "GNU") AND (CMAKE_CXX_COMPILER_VERSION VERSION_GREATER 8.99.9)) OR
-      ((CMAKE_CXX_COMPILER_ID STREQUAL "Clang") AND (CMAKE_CXX_COMPILER_VERSION VERSION_GREATER 9.99.9)) OR
-      ((CMAKE_CXX_COMPILER_ID STREQUAL "Intel") AND (CMAKE_CXX_COMPILER_VERSION VERSION_GREATER 18.99.9))
-      )
+  if (((CMAKE_CXX_COMPILER_ID STREQUAL "GNU") AND (CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 9.0)) 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.
     # Intel 18.0 was tested to support both, so we switch to OpenMP 4+ from 19.x onward to be safe.
     target_compile_definitions(lammps PRIVATE -DLAMMPS_OMP_COMPAT=4)
@@ -249,6 +249,26 @@ if(${CMAKE_CXX_COMPILER_ID} STREQUAL "GNU")
   endif()
 endif()
 
+#######################################
+# add custom target for IWYU analysis
+#######################################
+set(ENABLE_IWYU OFF CACHE BOOL "Add 'iwyu' build target to call the include-what-you-use tool")
+mark_as_advanced(ENABLE_IWYU)
+if(ENABLE_IWYU)
+  find_program(IWYU_EXE NAMES include-what-you-use iwyu)
+  find_program(IWYU_TOOL NAMES iwyu_tool iwyu-tool iwyu_tool.py)
+  if (IWYU_EXE AND IWYU_TOOL)
+    add_custom_target(
+      iwyu
+      ${IWYU_TOOL} -o clang -p ${CMAKE_CURRENT_BINARY_DIR} -- -Xiwyu --mapping_file=${CMAKE_CURRENT_SOURCE_DIR}/iwyu/iwyu-extra-map.imp
+      COMMENT "Running IWYU")
+    add_dependencies(iwyu lammps)
+  else()
+    message(FATAL_ERROR "To use IWYU you need the include-what-you-use/iwyu executable"
+      "and the iwyu-tool/iwyu_tool script installed in your PATH")
+  endif()
+endif()
+
 set(ENABLE_SANITIZER "none" CACHE STRING "Select a code sanitizer option (none (default), address, leak, thread, undefined)")
 mark_as_advanced(ENABLE_SANITIZER)
 set(ENABLE_SANITIZER_VALUES none address leak thread undefined)
@@ -293,14 +313,13 @@ if(PKG_MSCG OR PKG_USER-ATC OR PKG_USER-AWPMD OR PKG_USER-QUIP OR PKG_LATTE)
   endif()
 endif()
 
-
 find_package(JPEG QUIET)
 option(WITH_JPEG "Enable JPEG support" ${JPEG_FOUND})
 if(WITH_JPEG)
   find_package(JPEG REQUIRED)
   target_compile_definitions(lammps PRIVATE -DLAMMPS_JPEG)
   if(CMAKE_VERSION VERSION_LESS 3.12)
-    target_include_directories(lammps PRIVATE ${JPEG_INCLUDE_DIR})
+    target_include_directories(lammps PRIVATE ${JPEG_INCLUDE_DIRS})
     target_link_libraries(lammps PRIVATE ${JPEG_LIBRARIES})
   else()
     target_link_libraries(lammps PRIVATE JPEG::JPEG)
@@ -325,20 +344,22 @@ find_program(GZIP_EXECUTABLE gzip)
 find_package_handle_standard_args(GZIP REQUIRED_VARS GZIP_EXECUTABLE)
 option(WITH_GZIP "Enable GZIP support" ${GZIP_FOUND})
 if(WITH_GZIP)
-  if(NOT GZIP_FOUND)
+  if(GZIP_FOUND OR ((CMAKE_SYSTEM_NAME STREQUAL Windows) AND CMAKE_CROSSCOMPILING))
+    target_compile_definitions(lammps PRIVATE -DLAMMPS_GZIP)
+  else()
     message(FATAL_ERROR "gzip executable not found")
   endif()
-  target_compile_definitions(lammps PRIVATE -DLAMMPS_GZIP)
 endif()
 
 find_program(FFMPEG_EXECUTABLE ffmpeg)
 find_package_handle_standard_args(FFMPEG REQUIRED_VARS FFMPEG_EXECUTABLE)
 option(WITH_FFMPEG "Enable FFMPEG support" ${FFMPEG_FOUND})
 if(WITH_FFMPEG)
-  if(NOT FFMPEG_FOUND)
+  if(FFMPEG_FOUND OR ((CMAKE_SYSTEM_NAME STREQUAL Windows) AND CMAKE_CROSSCOMPILING))
+    target_compile_definitions(lammps PRIVATE -DLAMMPS_FFMPEG)
+  else()
     message(FATAL_ERROR "ffmpeg executable not found")
   endif()
-  target_compile_definitions(lammps PRIVATE -DLAMMPS_FFMPEG)
 endif()
 
 if(BUILD_SHARED_LIBS)
@@ -556,7 +577,7 @@ if (${_index} GREATER -1)
 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
   input.h info.h kspace.h lammps.h lattice.h library.h lmppython.h lmptype.h memory.h modify.h neighbor.h neigh_list.h output.h
-  pair.h pointers.h region.h timer.h universe.h update.h variable.h)
+  pair.h pointers.h region.h timer.h universe.h update.h utils.h variable.h)
 if(LAMMPS_EXCEPTIONS)
   list(APPEND LAMMPS_CXX_HEADERS exceptions.h)
 endif()
@@ -592,36 +613,7 @@ if(BUILD_SHARED_LIBS)
 endif()
 install(FILES ${LAMMPS_DOC_DIR}/lammps.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1 RENAME ${LAMMPS_BINARY}.1)
 
-if(BUILD_TOOLS)
-  add_executable(binary2txt ${LAMMPS_TOOLS_DIR}/binary2txt.cpp)
-  target_compile_definitions(binary2txt PRIVATE -DLAMMPS_${LAMMPS_SIZES})
-  install(TARGETS binary2txt DESTINATION ${CMAKE_INSTALL_BINDIR})
-
-  include(CheckGeneratorSupport)
-  if(CMAKE_GENERATOR_SUPPORT_FORTRAN)
-    include(CheckLanguage)
-    check_language(Fortran)
-    if(CMAKE_Fortran_COMPILER)
-      enable_language(Fortran)
-      add_executable(chain.x ${LAMMPS_TOOLS_DIR}/chain.f)
-      target_link_libraries(chain.x PRIVATE ${CMAKE_Fortran_IMPLICIT_LINK_LIBRARIES})
-      install(TARGETS chain.x DESTINATION ${CMAKE_INSTALL_BINDIR})
-    else()
-      message(WARNING "No suitable Fortran compiler found, skipping building 'chain.x'")
-    endif()
-  else()
-    message(WARNING "CMake build doesn't support fortran, skipping building 'chain.x'")
-  endif()
-
-  enable_language(C)
-  get_filename_component(MSI2LMP_SOURCE_DIR ${LAMMPS_TOOLS_DIR}/msi2lmp/src ABSOLUTE)
-  file(GLOB MSI2LMP_SOURCES ${MSI2LMP_SOURCE_DIR}/[^.]*.c)
-  add_executable(msi2lmp ${MSI2LMP_SOURCES})
-  target_link_libraries(msi2lmp PRIVATE ${MATH_LIBRARIES})
-  install(TARGETS msi2lmp DESTINATION ${CMAKE_INSTALL_BINDIR})
-  install(FILES ${LAMMPS_DOC_DIR}/msi2lmp.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1)
-endif()
-
+include(Tools)
 include(Documentation)
 
 ###############################################################################
@@ -717,6 +709,7 @@ get_target_property(DEFINES lammps COMPILE_DEFINITIONS)
 include(FeatureSummary)
 feature_summary(DESCRIPTION "The following tools and libraries have been found and configured:" WHAT PACKAGES_FOUND)
 message(STATUS "<<< Build configuration >>>
+   Operating System: ${CMAKE_SYSTEM_NAME}
    Build type:       ${CMAKE_BUILD_TYPE}
    Install path:     ${CMAKE_INSTALL_PREFIX}
    Generator:        ${CMAKE_GENERATOR} using ${CMAKE_MAKE_PROGRAM}
@@ -816,3 +809,9 @@ endif()
 if(BUILD_DOC)
   message(STATUS "<<< Building HTML Manual >>>")
 endif()
+if(BUILD_TOOLS)
+  message(STATUS "<<< Building Tools >>>")
+endif()
+if(BUILD_LAMMPS_SHELL)
+  message(STATUS "<<< Building LAMMPS Shell >>>")
+endif()

cmake/Modules/CodeCoverage.cmake

@@ -3,11 +3,16 @@
 #
 # Requires latest gcovr (for GCC 8.1 support):#
 # pip install git+https://github.com/gcovr/gcovr.git
+#
+# For Python coverage the coverage package needs to be installed
 ###############################################################################
 if(ENABLE_COVERAGE)
     find_program(GCOVR_BINARY gcovr)
     find_package_handle_standard_args(GCOVR DEFAULT_MSG GCOVR_BINARY)
 
+    find_program(COVERAGE_BINARY coverage)
+    find_package_handle_standard_args(COVERAGE DEFAULT_MSG COVERAGE_BINARY)
+
     if(GCOVR_FOUND)
         get_filename_component(ABSOLUTE_LAMMPS_SOURCE_DIR ${LAMMPS_SOURCE_DIR} ABSOLUTE)
 
@@ -46,4 +51,30 @@ if(ENABLE_COVERAGE)
         )
         add_dependencies(reset_coverage clean_coverage_html)
     endif()
+
+    if(COVERAGE_FOUND)
+        set(PYTHON_COVERAGE_HTML_DIR ${CMAKE_BINARY_DIR}/python_coverage_html)
+        add_custom_command(
+            OUTPUT ${CMAKE_BINARY_DIR}/unittest/python/.coverage
+            COMMAND ${COVERAGE_BINARY} combine
+            WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/unittest/python
+            COMMENT "Combine Python coverage files..."
+        )
+
+        add_custom_target(
+            gen_python_coverage_html
+            COMMAND ${COVERAGE_BINARY} html -d ${PYTHON_COVERAGE_HTML_DIR}
+            DEPENDS ${CMAKE_BINARY_DIR}/unittest/python/.coverage
+            WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/unittest/python
+            COMMENT "Generating HTML Python coverage report..."
+        )
+
+        add_custom_target(
+            gen_python_coverage_xml
+            COMMAND ${COVERAGE_BINARY} xml -o ${CMAKE_BINARY_DIR}/python_coverage.xml
+            DEPENDS ${CMAKE_BINARY_DIR}/unittest/python/.coverage
+            WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/unittest/python
+            COMMENT "Generating XML Python coverage report..."
+        )
+    endif()
 endif()

cmake/Modules/Documentation.cmake

@@ -15,75 +15,93 @@ if(BUILD_DOC)
     endif()
     set(VIRTUALENV ${Python3_EXECUTABLE} -m virtualenv -p ${Python3_EXECUTABLE})
   endif()
+  find_package(Doxygen 1.8.10 REQUIRED)
 
   file(GLOB DOC_SOURCES ${LAMMPS_DOC_DIR}/src/[^.]*.rst)
 
+
   add_custom_command(
     OUTPUT docenv
     COMMAND ${VIRTUALENV} docenv
   )
 
   set(DOCENV_BINARY_DIR ${CMAKE_BINARY_DIR}/docenv/bin)
+  set(DOCENV_REQUIREMENTS_FILE ${LAMMPS_DOC_DIR}/utils/requirements.txt)
+
+  set(SPHINX_CONFIG_DIR ${LAMMPS_DOC_DIR}/utils/sphinx-config)
+  set(SPHINX_CONFIG_FILE_TEMPLATE ${SPHINX_CONFIG_DIR}/conf.py.in)
+  set(SPHINX_STATIC_DIR  ${SPHINX_CONFIG_DIR}/_static)
+
+  # configuration and static files are copied to binary dir to avoid collisions with parallel builds
+  set(DOC_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR}/doc)
+  set(DOC_BUILD_CONFIG_FILE ${DOC_BUILD_DIR}/conf.py)
+  set(DOC_BUILD_STATIC_DIR ${DOC_BUILD_DIR}/_static)
+  set(DOXYGEN_BUILD_DIR ${DOC_BUILD_DIR}/doxygen)
+  set(DOXYGEN_XML_DIR ${DOXYGEN_BUILD_DIR}/xml)
+
+  # copy entire configuration folder to doc build directory
+  # files in _static are automatically copied during sphinx-build, so no need to copy them individually
+  file(COPY ${SPHINX_CONFIG_DIR}/ DESTINATION ${DOC_BUILD_DIR})
+
+  # configure paths in conf.py, since relative paths change when file is copied
+  configure_file(${SPHINX_CONFIG_FILE_TEMPLATE} ${DOC_BUILD_CONFIG_FILE})
 
   add_custom_command(
-    OUTPUT requirements.txt
-    DEPENDS docenv
-    COMMAND ${CMAKE_COMMAND} -E copy ${LAMMPS_DOC_DIR}/utils/requirements.txt requirements.txt
+    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 requirements.txt --upgrade
+    COMMAND ${DOCENV_BINARY_DIR}/pip install --use-feature=2020-resolver -r ${DOC_BUILD_DIR}/requirements.txt --upgrade
   )
 
   # download mathjax distribution and unpack to folder "mathjax"
-  if(NOT EXISTS ${CMAKE_CURRENT_BINARY_DIR}/mathjax/es5)
+  if(NOT EXISTS ${DOC_BUILD_STATIC_DIR}/mathjax/es5)
     file(DOWNLOAD "https://github.com/mathjax/MathJax/archive/3.0.5.tar.gz"
       "${CMAKE_CURRENT_BINARY_DIR}/mathjax.tar.gz"
       EXPECTED_MD5 5d9d3799cce77a1a95eee6be04eb68e7)
     execute_process(COMMAND ${CMAKE_COMMAND} -E tar xzf mathjax.tar.gz WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
     file(GLOB MATHJAX_VERSION_DIR ${CMAKE_CURRENT_BINARY_DIR}/MathJax-*)
-    execute_process(COMMAND ${CMAKE_COMMAND} -E rename ${MATHJAX_VERSION_DIR} ${CMAKE_CURRENT_BINARY_DIR}/mathjax)
+    execute_process(COMMAND ${CMAKE_COMMAND} -E rename ${MATHJAX_VERSION_DIR} ${DOC_BUILD_STATIC_DIR}/mathjax)
   endif()
-  file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/_static/mathjax)
-  file(COPY ${CMAKE_CURRENT_BINARY_DIR}/mathjax/es5 DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/html/_static/mathjax/)
 
   # for increased browser compatibility
-  if(NOT EXISTS ${CMAKE_CURRENT_BINARY_DIR}/html/_static/polyfill.js)
+  if(NOT EXISTS ${DOC_BUILD_STATIC_DIR}/polyfill.js)
     file(DOWNLOAD "https://polyfill.io/v3/polyfill.min.js?features=es6"
-      "${CMAKE_CURRENT_BINARY_DIR}/html/_static/polyfill.js")
+      "${DOC_BUILD_STATIC_DIR}/polyfill.js")
   endif()
 
-  # note, this may run in parallel with other tasks, so we must not use multiple processes here
+  # set up doxygen and add targets to run it
+  file(MAKE_DIRECTORY ${DOXYGEN_BUILD_DIR})
+  file(COPY ${LAMMPS_DOC_DIR}/doxygen/lammps-logo.png DESTINATION ${DOXYGEN_BUILD_DIR}/lammps-logo.png)
+  configure_file(${LAMMPS_DOC_DIR}/doxygen/Doxyfile.in ${DOXYGEN_BUILD_DIR}/Doxyfile)
+  get_target_property(LAMMPS_SOURCES lammps SOURCES)
   add_custom_command(
-    OUTPUT html
-    DEPENDS ${DOC_SOURCES} docenv requirements.txt
-    COMMAND ${DOCENV_BINARY_DIR}/sphinx-build -b html -c ${LAMMPS_DOC_DIR}/utils/sphinx-config -d ${CMAKE_BINARY_DIR}/doctrees ${LAMMPS_DOC_DIR}/src html
-    COMMAND ${CMAKE_COMMAND} -E create_symlink Manual.html ${CMAKE_CURRENT_BINARY_DIR}/html/index.html
+    OUTPUT ${DOXYGEN_XML_DIR}/index.xml
+    DEPENDS ${DOC_SOURCES} ${LAMMPS_SOURCES}
+    COMMAND Doxygen::doxygen ${DOXYGEN_BUILD_DIR}/Doxyfile WORKING_DIRECTORY ${DOXYGEN_BUILD_DIR}
+    COMMAND ${CMAKE_COMMAND} -E touch ${DOXYGEN_XML_DIR}/run.stamp
   )
 
-  # copy selected image files to html output tree
-  file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/html/JPG)
-  set(HTML_EXTRA_IMAGES balance_nonuniform.jpg balance_rcb.jpg
-    balance_uniform.jpg bow_tutorial_01.png bow_tutorial_02.png
-    bow_tutorial_03.png bow_tutorial_04.png bow_tutorial_05.png
-    dump1.jpg dump2.jpg examples_mdpd.gif gran_funnel.png gran_mixer.png
-    hop1.jpg hop2.jpg saed_ewald_intersect.jpg saed_mesh.jpg
-    screenshot_atomeye.jpg screenshot_gl.jpg screenshot_pymol.jpg
-    screenshot_vmd.jpg sinusoid.jpg xrd_mesh.jpg)
-  set(HTML_IMAGE_TARGETS "")
-  foreach(_IMG ${HTML_EXTRA_IMAGES})
-    string(PREPEND _IMG JPG/)
-    list(APPEND HTML_IMAGE_TARGETS "${CMAKE_CURRENT_BINARY_DIR}/html/${_IMG}")
-    add_custom_command(
-      OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/html/${_IMG}
-      DEPENDS ${LAMMPS_DOC_DIR}/src/${_IMG} ${CMAKE_CURRENT_BINARY_DIR}/html/JPG
-      COMMAND ${CMAKE_COMMAND} -E copy ${LAMMPS_DOC_DIR}/src/${_IMG} ${CMAKE_BINARY_DIR}/html/${_IMG}
-    )
-  endforeach()
+  if(EXISTS ${DOXYGEN_XML_DIR}/run.stamp)
+    set(SPHINX_EXTRA_OPTS "-E")
+  else()
+    set(SPHINX_EXTRA_OPTS "")
+  endif()
+  add_custom_command(
+    OUTPUT html
+    DEPENDS ${DOC_SOURCES} docenv ${DOC_BUILD_DIR}/requirements.txt ${DOXYGEN_XML_DIR}/index.xml ${BUILD_DOC_CONFIG_FILE}
+    COMMAND ${DOCENV_BINARY_DIR}/sphinx-build ${SPHINX_EXTRA_OPTS} -b html -c ${DOC_BUILD_DIR} -d ${DOC_BUILD_DIR}/doctrees ${LAMMPS_DOC_DIR}/src ${DOC_BUILD_DIR}/html
+    COMMAND ${CMAKE_COMMAND} -E create_symlink Manual.html ${DOC_BUILD_DIR}/html/index.html
+    COMMAND ${CMAKE_COMMAND} -E copy_directory ${LAMMPS_DOC_DIR}/src/PDF ${DOC_BUILD_DIR}/html/PDF
+    COMMAND ${CMAKE_COMMAND} -E remove -f ${DOXYGEN_XML_DIR}/run.stamp
+  )
 
   add_custom_target(
     doc ALL
-    DEPENDS html ${CMAKE_CURRENT_BINARY_DIR}/html/_static/mathjax/es5 ${HTML_IMAGE_TARGETS}
+    DEPENDS html ${DOC_BUILD_STATIC_DIR}/mathjax/es5
     SOURCES ${LAMMPS_DOC_DIR}/utils/requirements.txt ${DOC_SOURCES}
   )
 
-  install(DIRECTORY ${CMAKE_BINARY_DIR}/html DESTINATION ${CMAKE_INSTALL_DOCDIR})
+  install(DIRECTORY ${DOC_BUILD_DIR}/html DESTINATION ${CMAKE_INSTALL_DOCDIR})
 endif()

cmake/Modules/GenerateBinaryHeader.cmake

@@ -1,3 +1,3 @@
 # utility script to call GenerateBinaryHeader function
 include(${SOURCE_DIR}/Modules/LAMMPSUtils.cmake)
-GenerateBinaryHeader(${VARNAME} ${HEADER_FILE} ${SOURCE_FILES})
+GenerateBinaryHeader(${VARNAME} ${HEADER_FILE} ${SOURCE_FILE})

cmake/Modules/LAMMPSUtils.cmake

@@ -71,19 +71,15 @@ macro(pkg_depends PKG1 PKG2)
 endmacro()
 
 # CMake-only replacement for bin2c and xxd
-function(GenerateBinaryHeader varname outfile files)
+function(GenerateBinaryHeader varname outfile infile)
     message("Creating ${outfile}...")
     file(WRITE ${outfile} "// CMake generated file\n")
-    math(EXPR ARG_END   "${ARGC}-1")
 
-    foreach(IDX RANGE 2 ${ARG_END})
-        list(GET ARGV ${IDX} filename)
-        file(READ ${filename} content HEX)
-        string(REGEX REPLACE "([0-9a-f][0-9a-f])" "0x\\1," content "${content}")
-        string(REGEX REPLACE ",$" "" content "${content}")
-        file(APPEND ${outfile} "const unsigned char ${varname}[] = { ${content} };\n")
-        file(APPEND ${outfile} "const unsigned int ${varname}_size = sizeof(${varname});\n")
-    endforeach()
+    file(READ ${infile} content HEX)
+    string(REGEX REPLACE "([0-9a-f][0-9a-f])" "0x\\1," content "${content}")
+    string(REGEX REPLACE ",$" "" content "${content}")
+    file(APPEND ${outfile} "const unsigned char ${varname}[] = { ${content} };\n")
+    file(APPEND ${outfile} "const unsigned int ${varname}_size = sizeof(${varname});\n")
 endfunction(GenerateBinaryHeader)
 
 # fetch missing potential files

cmake/Modules/Packages/COMPRESS.cmake

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

cmake/Modules/Packages/GPU.cmake

@@ -75,7 +75,7 @@ if(GPU_API STREQUAL "CUDA")
   endif()
   # Kepler (GPU Arch 3.5) is supported by CUDA 5 to CUDA 11
   if((CUDA_VERSION VERSION_GREATER_EQUAL "5.0") AND (CUDA_VERSION VERSION_LESS "12.0"))
-    string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_30,code=[sm_30,compute_30] -gencode arch=compute_35,code=[sm_35,compute_35]")
+    string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_35,code=[sm_35,compute_35]")
   endif()
   # Maxwell (GPU Arch 5.x) is supported by CUDA 6 and later
   if(CUDA_VERSION VERSION_GREATER_EQUAL "6.0")
@@ -309,7 +309,7 @@ elseif(GPU_API STREQUAL "HIP")
     endif()
 
     add_custom_command(OUTPUT ${CUBIN_H_FILE}
-      COMMAND ${CMAKE_COMMAND} -D SOURCE_DIR=${CMAKE_CURRENT_SOURCE_DIR} -D VARNAME=${CU_NAME} -D HEADER_FILE=${CUBIN_H_FILE} -D SOURCE_FILES=${CUBIN_FILE} -P ${CMAKE_CURRENT_SOURCE_DIR}/Modules/GenerateBinaryHeader.cmake
+      COMMAND ${CMAKE_COMMAND} -D SOURCE_DIR=${CMAKE_CURRENT_SOURCE_DIR} -D VARNAME=${CU_NAME} -D HEADER_FILE=${CUBIN_H_FILE} -D SOURCE_FILE=${CUBIN_FILE} -P ${CMAKE_CURRENT_SOURCE_DIR}/Modules/GenerateBinaryHeader.cmake
       DEPENDS ${CUBIN_FILE}
       COMMENT "Generating ${CU_NAME}_cubin.h")
 

cmake/Modules/Packages/KOKKOS.cmake

@@ -35,8 +35,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.1.01.tar.gz
-    URL_MD5 3ccb2100f7fc316891e7dad3bc33fa37
+    URL https://github.com/kokkos/kokkos/archive/3.2.00.tar.gz
+    URL_MD5 81569170fe232e5e64ab074f7cca5e50
     CMAKE_ARGS ${KOKKOS_LIB_BUILD_ARGS}
     BUILD_BYPRODUCTS <INSTALL_DIR>/lib/libkokkoscore.a
   )
@@ -50,7 +50,7 @@ if(DOWNLOAD_KOKKOS)
   target_link_libraries(lammps PRIVATE LAMMPS::KOKKOS)
   add_dependencies(LAMMPS::KOKKOS kokkos_build)
 elseif(EXTERNAL_KOKKOS)
-  find_package(Kokkos 3.1.01 REQUIRED CONFIG)
+  find_package(Kokkos 3.2.00 REQUIRED CONFIG)
   target_link_libraries(lammps PRIVATE Kokkos::kokkos)
 else()
   set(LAMMPS_LIB_KOKKOS_SRC_DIR ${LAMMPS_LIB_SOURCE_DIR}/kokkos)

cmake/Modules/Packages/KSPACE.cmake

@@ -19,16 +19,16 @@ if(FFT STREQUAL "FFTW3")
   find_package(${FFTW} REQUIRED)
   target_compile_definitions(lammps PRIVATE -DFFT_FFTW3)
   target_link_libraries(lammps PRIVATE ${FFTW}::${FFTW})
-  if(FFTW3_OMP_LIBRARY OR FFTW3F_OMP_LIBRARY)
+  if(FFTW3_OMP_LIBRARIES OR FFTW3F_OMP_LIBRARIES)
     option(FFT_FFTW_THREADS "Use threaded FFTW library" ON)
   else()
     option(FFT_FFTW_THREADS "Use threaded FFT library" OFF)
   endif()
 
   if(FFT_FFTW_THREADS)
-    if(FFTW3_OMP_LIBRARY OR FFTW3F_OMP_LIBRARY)
-	target_compile_definitions(lammps PRIVATE -DFFT_FFTW_THREADS)
-	target_link_libraries(lammps PRIVATE ${FFTW}::${FFTW}_OMP)
+    if(FFTW3_OMP_LIBRARIES OR FFTW3F_OMP_LIBRARIES)
+      target_compile_definitions(lammps PRIVATE -DFFT_FFTW_THREADS)
+      target_link_libraries(lammps PRIVATE ${FFTW}::${FFTW}_OMP)
     else()
       message(FATAL_ERROR "Need OpenMP enabled FFTW3 library for FFT_THREADS")
     endif()

cmake/Modules/Packages/MSCG.cmake

@@ -38,7 +38,7 @@ if(DOWNLOAD_MSCG)
 else()
   find_package(MSCG)
   if(NOT MSCG_FOUND)
-    message(FATAL_ERROR "MSCG not found, help CMake to find it by setting MSCG_LIBRARY and MSCG_INCLUDE_DIRS, or set DOWNLOAD_MSCG=ON to download it")
+    message(FATAL_ERROR "MSCG not found, help CMake to find it by setting MSCG_LIBRARY and MSCG_INCLUDE_DIR, or set DOWNLOAD_MSCG=ON to download it")
   endif()
   target_link_libraries(lammps PRIVATE MSCG::MSCG)
 endif()

cmake/Modules/Packages/PYTHON.cmake

@@ -1,7 +1,7 @@
 if(CMAKE_VERSION VERSION_LESS 3.12)
   find_package(PythonLibs REQUIRED) # Deprecated since version 3.12
-  target_include_directories(lammps PRIVATE ${PYTHON_INCLUDE_DIR})
-  target_link_libraries(lammps PRIVATE ${PYTHON_LIBRARY})
+  target_include_directories(lammps PRIVATE ${PYTHON_INCLUDE_DIRS})
+  target_link_libraries(lammps PRIVATE ${PYTHON_LIBRARIES})
 else()
   find_package(Python REQUIRED COMPONENTS Development)
   target_link_libraries(lammps PRIVATE Python::Python)

cmake/Modules/Packages/USER-COLVARS.cmake

@@ -2,6 +2,8 @@ set(COLVARS_SOURCE_DIR ${LAMMPS_LIB_SOURCE_DIR}/colvars)
 
 file(GLOB COLVARS_SOURCES ${COLVARS_SOURCE_DIR}/[^.]*.cpp)
 
+option(COLVARS_DEBUG "Debugging messages for Colvars (quite verbose)" OFF)
+
 # Build Lepton by default
 option(COLVARS_LEPTON "Build and link the Lepton library" ON)
 
@@ -16,11 +18,18 @@ if(COLVARS_LEPTON)
 endif()
 
 add_library(colvars STATIC ${COLVARS_SOURCES})
-target_compile_definitions(colvars PRIVATE -DLAMMPS_${LAMMPS_SIZES})
+target_compile_definitions(colvars PRIVATE -DCOLVARS_LAMMPS)
 set_target_properties(colvars PROPERTIES OUTPUT_NAME lammps_colvars${LAMMPS_MACHINE})
 target_include_directories(colvars PUBLIC ${LAMMPS_LIB_SOURCE_DIR}/colvars)
+# The line below is needed to locate math_eigen_impl.h
+target_include_directories(colvars PRIVATE ${LAMMPS_SOURCE_DIR})
 target_link_libraries(lammps PRIVATE colvars)
 
+if(COLVARS_DEBUG)
+  # Need to export the macro publicly to also affect the proxy
+  target_compile_definitions(colvars PUBLIC -DCOLVARS_DEBUG)
+endif()
+
 if(COLVARS_LEPTON)
   target_link_libraries(lammps PRIVATE lepton)
   target_compile_definitions(colvars PRIVATE -DLEPTON)

cmake/Modules/Packages/USER-MOLFILE.cmake

@@ -1,4 +1,5 @@
-set(MOLFILE_INCLUDE_DIRS "${LAMMPS_LIB_SOURCE_DIR}/molfile" CACHE STRING "Path to VMD molfile plugin headers")
+set(MOLFILE_INCLUDE_DIR "${LAMMPS_LIB_SOURCE_DIR}/molfile" CACHE STRING "Path to VMD molfile plugin headers")
+set(MOLFILE_INCLUDE_DIRS "${MOLFILE_INCLUDE_DIR}")
 add_library(molfile INTERFACE)
 target_include_directories(molfile INTERFACE ${MOLFILE_INCLUDE_DIRS})
 # no need to link with -ldl on windows

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.0/plumed-src-2.6.0.tgz
-    URL_MD5 204d2edae58d9b10ba3ad460cad64191
+    URL https://github.com/plumed/plumed2/releases/download/v2.6.1/plumed-src-2.6.1.tgz
+    URL_MD5 89a9a450fc6025299fe16af235957163
     BUILD_IN_SOURCE 1
     CONFIGURE_COMMAND <SOURCE_DIR>/configure --prefix=<INSTALL_DIR>
                                              ${CONFIGURE_REQUEST_PIC}

cmake/Modules/Tools.cmake

@@ -0,0 +1,46 @@
+if(BUILD_TOOLS)
+  add_executable(binary2txt ${LAMMPS_TOOLS_DIR}/binary2txt.cpp)
+  target_compile_definitions(binary2txt PRIVATE -DLAMMPS_${LAMMPS_SIZES})
+  install(TARGETS binary2txt DESTINATION ${CMAKE_INSTALL_BINDIR})
+
+  include(CheckGeneratorSupport)
+  if(CMAKE_GENERATOR_SUPPORT_FORTRAN)
+    include(CheckLanguage)
+    check_language(Fortran)
+    if(CMAKE_Fortran_COMPILER)
+      enable_language(Fortran)
+      add_executable(chain.x ${LAMMPS_TOOLS_DIR}/chain.f)
+      target_link_libraries(chain.x PRIVATE ${CMAKE_Fortran_IMPLICIT_LINK_LIBRARIES})
+      install(TARGETS chain.x DESTINATION ${CMAKE_INSTALL_BINDIR})
+    else()
+      message(WARNING "No suitable Fortran compiler found, skipping build of 'chain.x'")
+    endif()
+  else()
+    message(WARNING "CMake build doesn't support fortran, skipping build of 'chain.x'")
+  endif()
+
+  enable_language(C)
+  get_filename_component(MSI2LMP_SOURCE_DIR ${LAMMPS_TOOLS_DIR}/msi2lmp/src ABSOLUTE)
+  file(GLOB MSI2LMP_SOURCES ${MSI2LMP_SOURCE_DIR}/[^.]*.c)
+  add_executable(msi2lmp ${MSI2LMP_SOURCES})
+  target_link_libraries(msi2lmp PRIVATE ${MATH_LIBRARIES})
+  install(TARGETS msi2lmp DESTINATION ${CMAKE_INSTALL_BINDIR})
+  install(FILES ${LAMMPS_DOC_DIR}/msi2lmp.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1)
+endif()
+
+if(BUILD_LAMMPS_SHELL)
+  find_package(PkgConfig REQUIRED)
+  pkg_check_modules(READLINE IMPORTED_TARGET REQUIRED readline)
+  if(NOT LAMMPS_EXCEPTIONS)
+    message(WARNING "The LAMMPS shell needs LAMMPS_EXCEPTIONS enabled for full functionality")
+  endif()
+  add_executable(lammps-shell ${LAMMPS_TOOLS_DIR}/lammps-shell/lammps-shell.cpp)
+  # workaround for broken readline pkg-config file on FreeBSD
+  if(CMAKE_SYSTEM_NAME STREQUAL FreeBSD)
+    target_include_directories(lammps-shell PRIVATE /usr/local/include)
+  endif()
+  target_link_libraries(lammps-shell PRIVATE lammps PkgConfig::READLINE)
+  install(TARGETS lammps-shell EXPORT LAMMPS_Targets DESTINATION ${CMAKE_INSTALL_BINDIR})
+endif()
+
+

cmake/iwyu/iwyu-extra-map.imp

@@ -0,0 +1,7 @@
+[
+  { include: [ "<bits/types/struct_rusage.h>", private, "<sys/resource.h>", public ] },
+  { include: [ "<bits/exception.h>", public, "<exception>", public ] },
+  { include: [ "@<Eigen/.*>", private, "<Eigen/Eigen>", public ] },
+  { include: [ "@<gtest/.*>", private, "\"gtest/gtest.h\"", public ] },
+  { include: [ "@<gmock/.*>", private, "\"gmock/gmock.h\"", public ] },
+]

cmake/presets/all_off.cmake

@@ -2,9 +2,9 @@
 # an existing package selection without losing any other settings
 
 set(ALL_PACKAGES ASPHERE BODY CLASS2 COLLOID COMPRESS CORESHELL DIPOLE GPU
-        GRANULAR KIM KOKKOS KSPACE LATTE MANYBODY MC MISC MESSAGE MOLECULE
-        MPIIO MSCG OPT PERI POEMS PYTHON QEQ REPLICA RIGID SHOCK SNAP SPIN
-        SRD VORONOI
+        GRANULAR KIM KOKKOS KSPACE LATTE MANYBODY MC MISC MESSAGE MLIAP
+        MOLECULE MPIIO MSCG OPT PERI POEMS PYTHON QEQ REPLICA RIGID SHOCK
+        SNAP SPIN SRD VORONOI
         USER-ADIOS USER-ATC USER-AWPMD USER-BOCS USER-CGDNA USER-CGSDK
         USER-COLVARS USER-DIFFRACTION USER-DPD USER-DRUDE USER-EFF USER-FEP
         USER-H5MD USER-INTEL USER-LB USER-MANIFOLD USER-MEAMC USER-MESODPD

cmake/presets/all_on.cmake

@@ -4,9 +4,9 @@
 # with just a working C++ compiler and an MPI library.
 
 set(ALL_PACKAGES ASPHERE BODY CLASS2 COLLOID COMPRESS CORESHELL DIPOLE GPU
-        GRANULAR KIM KOKKOS KSPACE LATTE MANYBODY MC MISC MESSAGE MOLECULE
-        MPIIO MSCG OPT PERI POEMS PYTHON QEQ REPLICA RIGID SHOCK SNAP SPIN
-        SRD VORONOI
+        GRANULAR KIM KOKKOS KSPACE LATTE MANYBODY MC MISC MESSAGE MLIAP
+        MOLECULE MPIIO MSCG OPT PERI POEMS PYTHON QEQ REPLICA RIGID SHOCK
+        SNAP SPIN SRD VORONOI
         USER-ADIOS USER-ATC USER-AWPMD USER-BOCS USER-CGDNA USER-CGSDK
         USER-COLVARS USER-DIFFRACTION USER-DPD USER-DRUDE USER-EFF USER-FEP
         USER-H5MD USER-INTEL USER-LB USER-MANIFOLD USER-MEAMC USER-MESODPD

cmake/presets/intel.cmake

@@ -1,7 +1,8 @@
-# preset that will enable clang/clang++ with support for MPI and OpenMP (on Linux boxes)
+# preset that will enable Intel compilers with support for MPI and OpenMP (on Linux boxes)
 
 set(CMAKE_CXX_COMPILER "icpc" CACHE STRING "" FORCE)
 set(CMAKE_C_COMPILER "icc" CACHE STRING "" FORCE)
+set(CMAKE_Fortran_COMPILER "ifort" CACHE STRING "" FORCE)
 set(MPI_CXX "icpc" CACHE STRING "" FORCE)
 set(MPI_CXX_COMPILER "mpicxx" CACHE STRING "" FORCE)
 unset(HAVE_OMP_H_INCLUDE CACHE)
@@ -12,5 +13,6 @@ set(OpenMP_C_LIB_NAMES "omp" CACHE STRING "" FORCE)
 set(OpenMP_CXX "icpc" CACHE STRING "" FORCE)
 set(OpenMP_CXX_FLAGS "-qopenmp" CACHE STRING "" FORCE)
 set(OpenMP_CXX_LIB_NAMES "omp" CACHE STRING "" FORCE)
+set(OpenMP_Fortran_FLAGS "-qopenmp" CACHE STRING "" FORCE)
 set(OpenMP_omp_LIBRARY "libiomp5.so" CACHE PATH "" FORCE)
 

doc/.gitignore

@@ -1,6 +1,7 @@
 /old
 /html
 /html-offline
+/epub
 /latex
 /mathjax
 /spelling
@@ -10,3 +11,9 @@
 /Developer.pdf
 /doctrees
 /docenv
+/doxygen-warn.log
+/utils/sphinx-config/conf.py
+/doxygen/Doxyfile
+*.el
+/utils/sphinx-config/_static/mathjax
+/utils/sphinx-config/_static/polyfill.js

doc/Makefile

@@ -1,21 +1,35 @@
 # Makefile for LAMMPS documentation
 
-SHELL         = /bin/bash
-BUILDDIR      = ${CURDIR}
-RSTDIR        = $(BUILDDIR)/src
-VENV          = $(BUILDDIR)/docenv
-MATHJAX       = $(BUILDDIR)/mathjax
-TXT2RST       = $(VENV)/bin/txt2rst
-ANCHORCHECK   = $(VENV)/bin/rst_anchor_check
+SHELL          = /bin/bash
+HAS_BASH       = YES
+ifeq (,$(wildcard $(SHELL)))
+OSHELL         := $(SHELL)
+override SHELL = /bin/sh
+HAS_BASH       = NO
+endif
+BUILDDIR       = ${CURDIR}
+RSTDIR         = $(BUILDDIR)/src
+VENV           = $(BUILDDIR)/docenv
+TXT2RST        = $(VENV)/bin/txt2rst
+ANCHORCHECK    = $(VENV)/bin/rst_anchor_check
+SPHINXCONFIG   = $(BUILDDIR)/utils/sphinx-config
+MATHJAX        = $(SPHINXCONFIG)/_static/mathjax
+POLYFILL       = $(SPHINXCONFIG)/_static/polyfill.js
 
-PYTHON        = $(shell which python3)
+PYTHON         = $(shell which python3)
+DOXYGEN        = $(shell which doxygen)
 VIRTUALENV     = virtualenv
 HAS_PYTHON3    = NO
 HAS_VIRTUALENV = NO
+HAS_DOXYGEN    = NO
 HAS_PDFLATEX   = NO
 
 ifeq ($(shell which python3 >/dev/null 2>&1; echo $$?), 0)
-HAS_PYTHON3 = YES
+HAS_PYTHON3    = YES
+endif
+
+ifeq ($(shell which doxygen >/dev/null 2>&1; echo $$?), 0)
+HAS_DOXYGEN    = YES
 endif
 
 ifeq ($(shell which virtualenv-3 >/dev/null 2>&1; echo $$?), 0)
@@ -29,20 +43,30 @@ HAS_VIRTUALENV = YES
 endif
 
 ifeq ($(shell which pdflatex >/dev/null 2>&1; echo $$?), 0)
+ifeq ($(shell which latexmk >/dev/null 2>&1; echo $$?), 0)
 HAS_PDFLATEX = YES
 endif
+endif
 
 
-SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())')
+#SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())') $(shell test -f $(BUILDDIR)/doxygen/xml/run.stamp && printf -- "-E")
 
-.PHONY: help clean-all clean clean-spelling epub mobi rst html pdf spelling anchor_check style_check
+# temporarily disable caching so that the hack for the sphinx-tabs extensions to get proper non-html output works
+SPHINXEXTRA = -E -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())')
+
+# grab list of sources from doxygen config file.
+# we only want to use explicitly listed files.
+DOXYFILES      = $(shell sed -n -e 's/\#.*$$//' -e '/^ *INPUT \+=/,/^[A-Z_]\+ \+=/p' doxygen/Doxyfile.in | sed -e 's/@LAMMPS_SOURCE_DIR@/..\/src/g' -e 's/\\//g' -e 's/ \+/ /' -e 's/[A-Z_]\+ \+= *\(YES\|NO\|\)//') 
+
+.PHONY: help clean-all clean clean-spelling epub mobi rst html pdf spelling anchor_check style_check xmlgen
 
 # ------------------------------------------
 
 help:
+	@if [ "$(HAS_BASH)" == "NO" ] ; then echo "bash was not found at $(OSHELL)! Please use: $(MAKE) SHELL=/path/to/bash" 1>&2; exit 1; fi
 	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html          create HTML doc pages in html dir"
-	@echo "  pdf           create Developer.pdf and Manual.pdf in this dir"
+	@echo "  html          create HTML pages in html dir"
+	@echo "  pdf           create Manual.pdf in this dir"
 	@echo "  fetch         fetch HTML and PDF files from LAMMPS web site"
 	@echo "  epub          create ePUB format manual for e-book readers"
 	@echo "  mobi          convert ePUB to MOBI format manual for e-book readers (e.g. Kindle)"
@@ -57,23 +81,33 @@ help:
 # ------------------------------------------
 
 clean-all: clean
-	rm -rf $(BUILDDIR)/docenv $(BUILDDIR)/doctrees $(BUILDDIR)/mathjax Manual.pdf Developer.pdf
+	rm -rf $(BUILDDIR)/docenv $(MATHJAX) $(POLYFILL) $(BUILDDIR)/LAMMPS.mobi $(BUILDDIR)/LAMMPS.epub $(BUILDDIR)/Manual.pdf
 
 clean: clean-spelling
-	rm -rf html epub latex
+	rm -rf $(BUILDDIR)/html $(BUILDDIR)/epub $(BUILDDIR)/latex $(BUILDDIR)/doctrees $(BUILDDIR)/doxygen/xml $(BUILDDIR)/doxygen-warn.log $(BUILDDIR)/doxygen/Doxyfile $(SPHINXCONFIG)/conf.py
 
 clean-spelling:
-	rm -rf spelling
+	rm -rf $(BUILDDIR)/spelling
 
-html: $(ANCHORCHECK) $(MATHJAX)
+$(SPHINXCONFIG)/conf.py: $(SPHINXCONFIG)/conf.py.in
+	sed -e 's,@DOXYGEN_XML_DIR@,$(BUILDDIR)/doxygen/xml,g'   \
+	    -e 's,@LAMMPS_SOURCE_DIR@,$(BUILDDIR)/../src,g'    \
+	    -e 's,@LAMMPS_PYTHON_DIR@,$(BUILDDIR)/../python,g' \
+	    -e 's,@LAMMPS_DOC_DIR@,$(BUILDDIR),g' $< > $@
+
+html: xmlgen $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX) $(POLYFILL)
+	@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
 	@(\
-		. $(VENV)/bin/activate ;\
-		sphinx-build $(SPHINXEXTRA) -b html -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) html ;\
+		. $(VENV)/bin/activate ; env PYTHONWARNINGS= \
+		sphinx-build $(SPHINXEXTRA) -b html -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) html ;\
+		ln -sf Manual.html html/index.html;\
+		rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\
 		echo "############################################" ;\
 		rst_anchor_check src/*.rst ;\
-		python utils/check-packages.py -s ../src -d src ;\
+		python $(BUILDDIR)/utils/check-packages.py -s ../src -d src ;\
 		env LC_ALL=C grep -n '[^ -~]' $(RSTDIR)/*.rst ;\
-		python utils/check-styles.py -s ../src -d src ;\
+		python $(BUILDDIR)/utils/check-styles.py -s ../src -d src ;\
 		echo "############################################" ;\
 		deactivate ;\
 	)
@@ -82,30 +116,30 @@ html: $(ANCHORCHECK) $(MATHJAX)
 	@rm -rf html/USER
 	@rm -rf html/JPG
 	@cp -r src/PDF html/PDF
-	@mkdir -p html/JPG
-	@cp `grep -A2 '\.\. .*\(image\|figure\)::' src/*.rst | grep ':target: JPG' | sed -e 's,.*:target: JPG/,src/JPG/,' | sort | uniq` html/JPG/
 	@rm -rf html/PDF/.[sg]*
-	@mkdir -p html/_static/mathjax
-	@cp -r $(MATHJAX)/es5 html/_static/mathjax/
 	@echo "Build finished. The HTML pages are in doc/html."
 
-spelling: $(VENV) utils/sphinx-config/false_positives.txt
+spelling: xmlgen $(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 ;\
-		cp utils/sphinx-config/false_positives.txt $(RSTDIR)/ ; env PYTHONWARNINGS= \
-		sphinx-build -b spelling -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) spelling ;\
+		. $(VENV)/bin/activate ; env PYTHONWARNINGS= \
+		cp $(SPHINXCONFIG)/false_positives.txt $(RSTDIR)/ ; env PYTHONWARNINGS= \
+		sphinx-build -b spelling -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) spelling ;\
+		rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\
 		deactivate ;\
 	)
 	@echo "Spell check finished."
 
-epub: $(VENV)
+epub: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK)
+	@if [ "$(HAS_BASH)" == "NO" ] ; then echo "bash was not found at $(OSHELL)! Please use: $(MAKE) SHELL=/path/to/bash" 1>&2; exit 1; fi
+	@$(MAKE) $(MFLAGS) -C graphviz all
 	@mkdir -p epub/JPG
 	@rm -f LAMMPS.epub
-	@cp src/JPG/lammps-logo.png epub/
 	@cp src/JPG/*.* epub/JPG
 	@(\
 		. $(VENV)/bin/activate ;\
-		sphinx-build $(SPHINXEXTRA) -b epub -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) epub ;\
+		sphinx-build $(SPHINXEXTRA) -b epub -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) epub ;\
+		rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\
 		deactivate ;\
 	)
 	@mv  epub/LAMMPS.epub .
@@ -117,18 +151,14 @@ mobi: epub
 	@ebook-convert LAMMPS.epub LAMMPS.mobi
 	@echo "Conversion finished. The MOBI manual file is created."
 
-pdf: $(ANCHORCHECK)
-	@if [ "$(HAS_PDFLATEX)" == "NO" ] ; then echo "PDFLaTeX was not found! Please check README.md for further instructions" 1>&2; exit 1; fi
+pdf: xmlgen $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK)
+	@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
+	@if [ "$(HAS_PDFLATEX)" == "NO" ] ; then echo "PDFLaTeX or latexmk were not found! Please check README for further instructions" 1>&2; exit 1; fi
 	@(\
-		cd src/Developer; \
-		pdflatex developer; \
-		pdflatex developer; \
-		mv developer.pdf ../../Developer.pdf; \
-		cd ../../; \
-	)
-	@(\
-		. $(VENV)/bin/activate ;\
-		sphinx-build $(SPHINXEXTRA) -b latex -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) latex ;\
+		. $(VENV)/bin/activate ; env PYTHONWARNINGS= \
+		sphinx-build $(SPHINXEXTRA) -b latex -c $(SPHINXCONFIG) -d $(BUILDDIR)/doctrees $(RSTDIR) latex ;\
+		rm -f $(BUILDDIR)/doxygen/xml/run.stamp;\
 		echo "############################################" ;\
 		rst_anchor_check src/*.rst ;\
 		python utils/check-packages.py -s ../src -d src ;\
@@ -138,15 +168,13 @@ pdf: $(ANCHORCHECK)
 		deactivate ;\
 	)
 	@cd latex && \
-		sed 's/latexmk -pdf -dvi- -ps-/pdflatex/g' Makefile > temp && \
-		mv temp Makefile && \
 		sed 's/\\begin{equation}//g' LAMMPS.tex > tmp.tex && \
 		mv tmp.tex LAMMPS.tex && \
 		sed 's/\\end{equation}//g' LAMMPS.tex > tmp.tex && \
 		mv tmp.tex LAMMPS.tex && \
-		make && \
-		make && \
-		make && \
+		sed 's/\\contentsname}{.*}}/\\contentsname}{LAMMPS Documentation}}/g' LAMMPS.tex > tmp.tex && \
+		mv tmp.tex LAMMPS.tex && \
+		$(MAKE) $(MFLAGS) && \
 		mv LAMMPS.pdf ../Manual.pdf && \
 		cd ../;
 	@rm -rf latex/_sources
@@ -154,12 +182,11 @@ pdf: $(ANCHORCHECK)
 	@rm -rf latex/USER
 	@cp -r src/PDF latex/PDF
 	@rm -rf latex/PDF/.[sg]*
-	@echo "Build finished. Manual.pdf and Developer.pdf are in this directory."
+	@echo "Build finished. Manual.pdf is in this directory."
 
 fetch:
-	@rm -rf html_www Manual_www.pdf Developer_www.pdf
+	@rm -rf html_www Manual_www.pdf
 	@curl -s -o Manual_www.pdf http://lammps.sandia.gov/doc/Manual.pdf
-	@curl -s -o Developer_www.pdf http://lammps.sandia.gov/doc/Developer.pdf
 	@curl -s -o lammps-doc.tar.gz http://lammps.sandia.gov/tars/lammps-doc.tar.gz
 	@tar xzf lammps-doc.tar.gz
 	@rm -f lammps-doc.tar.gz
@@ -185,21 +212,37 @@ package_check : $(VENV)
 		deactivate ;\
 	)
 
+xmlgen : doxygen/xml/index.xml
+
+doxygen/Doxyfile: doxygen/Doxyfile.in
+	sed -e 's/@LAMMPS_SOURCE_DIR@/..\/..\/src/g' $< > $@
+
+doxygen/xml/index.xml : $(VENV) doxygen/Doxyfile $(DOXYFILES)
+	@(cd doxygen; $(DOXYGEN) Doxyfile && touch xml/run.stamp)
 # ------------------------------------------
 
 $(VENV):
-	@if [ "$(HAS_PYTHON3)" == "NO" ] ; then echo "Python3 was not found! Please check README.md for further instructions" 1>&2; exit 1; fi
-	@if [ "$(HAS_VIRTUALENV)" == "NO" ] ; then echo "virtualenv was not found! Please check README.md for further instructions" 1>&2; exit 1; fi
+	@if [ "$(HAS_BASH)" == "NO" ] ; then echo "bash was not found at $(OSHELL)! Please use: $(MAKE) SHELL=/path/to/bash" 1>&2; exit 1; fi
+	@if [ "$(HAS_PYTHON3)" == "NO" ] ; then echo "python3 was not found! Please see README for further instructions" 1>&2; exit 1; fi
+	@if [ "$(HAS_DOXYGEN)" == "NO" ] ; then echo "doxygen was not found! Please see README for further instructions" 1>&2; exit 1; fi
+	@if [ "$(HAS_VIRTUALENV)" == "NO" ] ; then echo "virtualenv was not found! Please see README for further instructions" 1>&2; exit 1; fi
 	@( \
 		$(VIRTUALENV) -p $(PYTHON) $(VENV); \
 		. $(VENV)/bin/activate; \
 		pip install --upgrade pip; \
-		pip install --use-feature=2020-resolver -r requirements.txt; \
+		pip install --use-feature=2020-resolver -r $(BUILDDIR)/utils/requirements.txt; \
 		deactivate;\
 	)
 
 $(MATHJAX):
-	@git clone --depth 1 https://github.com/mathjax/MathJax.git mathjax
+	@git clone --depth 1 https://github.com/mathjax/MathJax.git $@
+
+# fall back to using wget and/or unencrypted download, if curl fails
+$(POLYFILL): $(MATHJAX)
+	@curl -s -o $@ "https://polyfill.io/v3/polyfill.min.js?features=es6" > /dev/null 2>&1  || \
+		curl -s -o $@ "http://polyfill.io/v3/polyfill.min.js?features=es6" > /dev/null 2>&1  || \
+		wget -O $@ "https://polyfill.io/v3/polyfill.min.js?features=es6" > /dev/null 2>&1  || \
+		wget -O $@ "http://polyfill.io/v3/polyfill.min.js?features=es6" > /dev/null 2>&1
 
 $(TXT2RST) $(ANCHORCHECK): $(VENV)
 	@( \

doc/README

@@ -1,97 +1,58 @@
 LAMMPS Documentation
 
-Depending on how you obtained LAMMPS, this directory has 2 or 3
-sub-directories and optionally 2 PDF files and an ePUB file:
+Depending on how you obtained LAMMPS and whether you have built
+the manual yourself, this directory has a varying number of
+sub-directories and files. Here is a list with descriptions:
 
-src             content files for LAMMPS documentation
-html            HTML version of the LAMMPS manual (see html/Manual.html)
-utils           utilities and settings for building the documentation
-Manual.pdf      large PDF version of entire manual
-Developer.pdf   small PDF with info about how LAMMPS is structured
-LAMMPS.epub     Manual in ePUB format
+README            this file
+src               content files for LAMMPS documentation
+html              HTML version of the LAMMPS manual (see html/Manual.html)
+utils             utilities and settings for building the documentation
+Manual.pdf        PDF version of entire manual
+LAMMPS.epub       Manual in ePUB format
+LAMMPS.mobi       Manual in MOBI (Kindle) format
+lammps.1          man page for the lammps command
+msi2lmp.1         man page for the msi2lmp command
+doctree           temporary data
+docenv            python virtual environment for generating the manual
+doxygen           Doxygen configuration and output
+.gitignore        list of files and folders to be ignored by git
+doxygen-warn.log  logfile with warnings from running doxygen
 
-If you downloaded LAMMPS as a tarball from the web site, all these
-directories and files should be included.
+and:
 
-If you downloaded LAMMPS from the public SVN or Git repositories, then
-the HTML and PDF files are not included.  Instead you need to create
-them, in one of three ways:
+github-development-workflow.md   notes on the LAMMPS development workflow
+include-file-conventions.md      notes on LAMMPS' include file conventions
+documentation_conventions.md     notes on writing documentation for LAMMPS
+
+If you downloaded a LAMMPS tarball from lammps.sandia.gov, then the html
+folder and the PDF manual should be included. If you downloaded LAMMPS
+from GitHub then you either need to download them or build them.
 
 (a) You can "fetch" the current HTML and PDF files from the LAMMPS web
-site.  Just type "make fetch".  This should create a html_www dir and
-Manual_www.pdf/Developer_www.pdf files.  Note that if new LAMMPS
-features have been added more recently than the date of your version,
-the fetched documentation will include those changes (but your source
-code will not, unless you update your local repository).
+site.  Just type "make fetch".  This should create a html_www directory
+and Manual_www.pdf file.  These will always represent the latest published
+patch/development version of LAMMPS.
 
-(b) You can build the HTML and PDF files yourself, by typing "make
-html" or by "make pdf", respectively.  This requires various tools
-including the Python documentation processing tool Sphinx, which the
-build process will attempt to download and install on your system into
-a python virtual environment, if not already available.  The PDF file
-will require a working LaTeX installation with several add-on packages
-in addition to the Python/Sphinx setup.  See more details below.
+(b) You can build the HTML and PDF files yourself, by typing "make html"
+or by "make pdf", respectively.  This requires various tools and files.
+Some of them have to be installed (more on that below).  For the rest the
+build process will attempt to download and install into a python virtual
+environment and local folders.
 
 ----------------
 
-The generation of all documentation is managed by the Makefile in this
-dir.
+Installing prerequisites for the documentation build
 
-Options:
+To run the HTML documention build toolchain, python 3.x, doxygen, git,
+and virtualenv have to be installed.  Also internet access is initially
+required to download external files and tools.
 
-make html         # generate HTML in html dir using Sphinx
-make pdf          # generate 2 PDF files (Manual.pdf,Developer.pdf)
-                  #   in this dir via Sphinx and PDFLaTeX
-make fetch        # fetch HTML doc pages and 2 PDF files from web site
-                  #   as a tarball and unpack into html dir and 2 PDFs
-make epub         # generate LAMMPS.epub in ePUB format using Sphinx
-make clean        # remove intermediate RST files created by HTML build
-make clean-all    # remove entire build folder and any cached data
-
-----------------
-
-Installing prerequisites for HTML build
-
-To run the HTML documention build toolchain, Python 3 and virtualenv
-have to be installed.  Here are instructions for common setups:
-
-# Ubuntu
-
-sudo apt-get install python-virtualenv
-
-# Fedora (up to version 21)
-# Red Hat Enterprise Linux or CentOS (up to version 7.x)
-
-sudo yum install python3-virtualenv
-
-# Fedora (since version 22)
-
-sudo dnf install python3-virtualenv
-
-# MacOS X
-
-## Python 3
-
-Download the latest Python 3 MacOS X package from
-https://www.python.org and install it.  This will install both Python
-3 and pip3.
-
-## virtualenv
-
-Once Python 3 is installed, open a Terminal and type
-
-pip3 install virtualenv
-
-This will install virtualenv from the Python Package Index.
-
-----------------
-
-Installing prerequisites for PDF build
-
-Same as for HTML plus a compatible LaTeX installation with
-support for PDFLaTeX. Also the following LaTeX packages need
-to be installed (e.g. from texlive):
+Building the PDF format manual requires in addition a compatible LaTeX
+installation with support for PDFLaTeX and several add-on LaTeX packages
+installed.  This includes:
 - amsmath
+- anysize
 - babel
 - capt-of
 - cmap
@@ -105,24 +66,16 @@ to be installed (e.g. from texlive):
 - tabulary
 - upquote
 - wrapfig
+Also the latexmk script is required to run PDFLaTeX and related tools.
+the required number of times to have self-consistent output and include
+updated bibliography and indices.
+
+Building the EPUB format requires LaTeX installation with the same packages
+as for the PDF format plus the 'dvipng' command to convert the embedded math
+into images. The MOBI format is generated from the EPUB format file by using
+the tool 'ebook-convert' from the 'calibre' e-book management software
+(https://calibre-ebook.com).
 ----------------
 
-Installing prerequisites for epub build
-
-## ePUB
-
-Same as for HTML. This uses the same tools and configuration
-files as the HTML tree. The ePUB format conversion currently
-does not support processing mathematical expressions via MathJAX,
-so there will be limitations on some pages. For the time being
-until this is resolved, building and using the PDF format file
-is recommended instead.
-
-For converting the generated ePUB file to a mobi format file
-(for e-book readers like Kindle, that cannot read ePUB), you
-also need to have the 'ebook-convert' tool from the "calibre"
-software installed. http://calibre-ebook.com/
-You first create the ePUB file with 'make epub' and then do:
-
-ebook-convert LAMMPS.epub LAMMPS.mobi
-
+More details this can be found in the manual itself. The online
+version is at: https://lammps.sandia.gov/doc/Manual_build.html

doc/documentation_conventions.md

@@ -0,0 +1,93 @@
+# Outline of LAMMPS documentation file conventions
+
+This purpose of this document is to provide a point of reference
+for LAMMPS developers and contributors as to what conventions
+should be used to structure and format files in the LAMMPS manual.
+
+Last change: 2020-04-23
+
+## File format and tools
+
+In fall 2019, the LAMMPS documentation file format has changed from
+a home grown minimal markup designed to generate HTML format files
+from a mostly plain text format to using the reStructuredText file
+format.  For a transition period all files in the old .txt format
+were transparently converted to .rst and then processed.  The txt2rst
+tool is still included in the distribution to obtain an initial .rst
+file for integration into the manual.  Since the transition to
+reStructured text as source format, many of the artifacts or the
+translation have been removed though and parts of the documentation
+refactored and expanded to take advantage of the capabilities
+reStructuredText and associated tools.  The conversion from the
+source to the final formats (HTML, PDF, and optionally e-book
+reader formats ePUB and MOBI) is mostly automated and controlled
+by a Makefile in the `doc` folder. This makefile assumes that the
+processing is done on a Unix-like machine and Python 3.5 or later
+and a matching virtualenv module are available.  Additional Python
+packages (like the Sphinx tool and several extensions) are
+transparently installed into a virtual environment over the
+internet using the `pip` package manager.  Further requirements
+and details are discussed in the manual.
+
+## Work in progress
+
+The refactoring and improving of the documentation is an ongoing
+process, so statements in this document may not always be fully
+up-to-date.  If in doubt, contact the LAMMPS developers.
+
+## General structure
+
+The layout and formatting of added files should follow the example
+of the existing files.  Since those are directly derived from their
+former .txt format versions and the manual has been maintained in
+that format for many years, there is a large degree of consistency
+already, so comparision with similar files should give you a good
+idea what kind of information and sections are needed.
+
+## Formatting conventions
+
+Filenames, folders, paths, (shell) commands, definitions, makefile
+settings and similar should be formatted as "literals" with
+double backward quotes bracketing the item: \`\`path/to/some/file\`\`
+
+Keywords and options are formatted in italics:  \*option\*
+
+Mathematical expressions, equations, symbols are typeset using
+either a `.. math:`` block or the `:math:` role.
+
+Groups of shell commands or LAMMPS input script or C/C++ source
+code should be typeset into a `.. code-block::` section. A syntax
+highlighting extension for LAMMPS input scripts is provided, so
+`LAMMPS` can be used to indicate the language in the code block
+in addition to `bash`, `c`, or `python`.  When no syntax style
+is indicated, no syntax highlighting is performed.
+
+As an alternative, e.g. to typeset the syntax of file formats
+a `.. parsed-literal::` block can be used, which allows some
+formatting directives, which means that related characters need
+to be escaped with a preceding backslash: `\*`.
+
+Special remarks can be highlighted with a `.. note::` block and
+strong warnings can be put into a `.. warning::` block.
+
+## Required steps when adding a custom style to LAMMPS
+
+When adding a new style (e.g. pair style or a compute or a fix)
+or a new command, it is **required** to include the corresponding
+documentation.  Those are often new files that need to be added.
+In order to be included in the documentation, those new files
+need to be reference in a `.. toctree::` block.  Most of those
+use patterns with wildcards, so the addition will be automatic.
+However, those additions also need to be added to some lists of
+styles or commands.  The `make style\_check` command will perform
+a test and report any missing entries and list the affected files.
+Any references defined with `.. \_refname:` have to be unique
+across all documentation files and this can be checked for with
+`make anchor\_check`.  Finally, a spell-check should be done,
+which is triggered via `make spelling`.  Any offenses need to
+be corrected and false positives should be added to the file
+`utils/sphinx-config/false\_positives.txt`.
+
+## Required additional steps when adding a new package to LAMMPS
+
+TODO

doc/doxygen/.gitignore

@@ -0,0 +1 @@
+/xml

doc/doxygen/Doxyfile.in

@@ -0,0 +1,533 @@
+# Doxyfile 1.8.15 -*- makefile -*-
+
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = "LAMMPS Programmer's Guide"
+PROJECT_NUMBER         = "24 August 2020"
+PROJECT_BRIEF          = "Documentation of the LAMMPS library interface and Python wrapper"
+PROJECT_LOGO           = lammps-logo.png
+CREATE_SUBDIRS         = NO
+ALLOW_UNICODE_NAMES    = NO
+OUTPUT_LANGUAGE        = English
+OUTPUT_TEXT_DIRECTION  = LTR
+
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = YES
+
+ALWAYS_DETAILED_SEC    = NO
+INLINE_INHERITED_MEMB  = NO
+FULL_PATH_NAMES        = NO
+INHERIT_DOCS           = YES
+TAB_SIZE               = 2
+
+# When enabled doxygen tries to link words that correspond to documented
+# classes, or namespaces to their corresponding documentation. Such a link can
+# be prevented in individual cases by putting a % sign in front of the word or
+# globally by setting AUTOLINK_SUPPORT to NO.
+# The default value is: YES.
+AUTOLINK_SUPPORT       = YES
+
+# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want
+# to include (a tag file for) the STL sources as input, then you should set this
+# tag to YES in order to let doxygen match functions declarations and
+# definitions whose arguments contain STL classes (e.g. func(std::string);
+# versus func(std::string) {}). This also make the inheritance and collaboration
+# diagrams that involve STL classes more complete and accurate.
+# The default value is: NO.
+
+BUILTIN_STL_SUPPORT    = YES
+IDL_PROPERTY_SUPPORT   = NO
+
+# The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This
+# cache is used to resolve symbols given their name and scope. Since this can be
+# an expensive process and often the same symbol appears multiple times in the
+# code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small
+# doxygen will become slower. If the cache is too large, memory is wasted. The
+# cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range
+# is 0..9, the default is 0, corresponding to a cache size of 2^16=65536
+# symbols. At the end of a run doxygen will report the cache usage and suggest
+# the optimal cache size from a speed point of view.
+# Minimum value: 0, maximum value: 9, default value: 0.
+
+LOOKUP_CACHE_SIZE      = 2
+
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+
+# If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in
+# documentation are documented, even if no documentation was available. Private
+# class members and static file members will be hidden unless the
+# EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES.
+# Note: This will also disable the warnings about undocumented members that are
+# normally produced when WARNINGS is set to YES.
+# The default value is: NO.
+
+EXTRACT_ALL            = NO
+
+# If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will
+# be included in the documentation.
+# The default value is: NO.
+
+EXTRACT_PRIVATE        = YES
+
+# If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal
+# scope will be included in the documentation.
+# The default value is: NO.
+
+EXTRACT_PACKAGE        = YES
+
+# If the EXTRACT_STATIC tag is set to YES, all static members of a file will be
+# included in the documentation.
+# The default value is: NO.
+
+EXTRACT_STATIC         = YES
+
+# If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined
+# locally in source files will be included in the documentation. If set to NO,
+# only classes defined in header files are included. Does not have any effect
+# for Java sources.
+# The default value is: YES.
+
+EXTRACT_LOCAL_CLASSES  = YES
+
+# If this flag is set to YES, the members of anonymous namespaces will be
+# extracted and appear in the documentation as a namespace called
+# 'anonymous_namespace{file}', where file will be replaced with the base name of
+# the file that contains the anonymous namespace. By default anonymous namespace
+# are hidden.
+# The default value is: NO.
+
+EXTRACT_ANON_NSPACES   = YES
+
+# If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all
+# undocumented members inside documented classes or files. If set to NO these
+# members will be included in the various overviews, but no documentation
+# section is generated. This option has no effect if EXTRACT_ALL is enabled.
+# The default value is: NO.
+
+HIDE_UNDOC_MEMBERS     = YES
+
+# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all
+# undocumented classes that are normally visible in the class hierarchy. If set
+# to NO, these classes will be included in the various overviews. This option
+# has no effect if EXTRACT_ALL is enabled.
+# The default value is: NO.
+
+HIDE_UNDOC_CLASSES     = YES
+
+# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend
+# (class|struct|union) declarations. If set to NO, these declarations will be
+# included in the documentation.
+# The default value is: NO.
+
+HIDE_FRIEND_COMPOUNDS  = NO
+
+# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any
+# documentation blocks found inside the body of a function. If set to NO, these
+# blocks will be appended to the function's detailed documentation block.
+# The default value is: NO.
+
+HIDE_IN_BODY_DOCS      = NO
+
+# The INTERNAL_DOCS tag determines if documentation that is typed after a
+# \internal command is included. If the tag is set to NO then the documentation
+# will be excluded. Set it to YES to include the internal documentation.
+# The default value is: NO.
+
+INTERNAL_DOCS          = NO
+
+# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file
+# names in lower-case letters. If set to YES, upper-case letters are also
+# allowed. This is useful if you have classes or files whose names only differ
+# in case and if your file system supports case sensitive file names. Windows
+# and Mac users are advised to set this option to NO.
+# The default value is: system dependent.
+
+CASE_SENSE_NAMES       = YES
+
+# If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with
+# their full class and namespace scopes in the documentation. If set to YES, the
+# scope will be hidden.
+# The default value is: NO.
+
+HIDE_SCOPE_NAMES       = YES
+
+# If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will
+# append additional text to a page's title, such as Class Reference. If set to
+# YES the compound reference will be hidden.
+# The default value is: NO.
+
+HIDE_COMPOUND_REFERENCE= NO
+
+# If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of
+# the files that are included by a file in the documentation of that file.
+# The default value is: YES.
+
+SHOW_INCLUDE_FILES     = NO
+
+# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each
+# grouped member an include statement to the documentation, telling the reader
+# which file to include in order to use the member.
+# The default value is: NO.
+
+SHOW_GROUPED_MEMB_INC  = NO
+
+# If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include
+# files with double quotes in the documentation rather than with sharp brackets.
+# The default value is: NO.
+
+FORCE_LOCAL_INCLUDES   = NO
+
+# If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the
+# documentation for inline members.
+# The default value is: YES.
+
+INLINE_INFO            = YES
+
+# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the
+# (detailed) documentation of file and class members alphabetically by member
+# name. If set to NO, the members will appear in declaration order.
+# The default value is: YES.
+
+SORT_MEMBER_DOCS       = NO
+
+# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief
+# descriptions of file, namespace and class members alphabetically by member
+# name. If set to NO, the members will appear in declaration order. Note that
+# this will also influence the order of the classes in the class list.
+# The default value is: NO.
+
+SORT_BRIEF_DOCS        = NO
+
+# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the
+# (brief and detailed) documentation of class members so that constructors and
+# destructors are listed first. If set to NO the constructors will appear in the
+# respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS.
+# Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief
+# member documentation.
+# Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting
+# detailed member documentation.
+# The default value is: NO.
+
+SORT_MEMBERS_CTORS_1ST = NO
+
+# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy
+# of group names into alphabetical order. If set to NO the group names will
+# appear in their defined order.
+# The default value is: NO.
+
+SORT_GROUP_NAMES       = NO
+
+# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by
+# fully-qualified names, including namespaces. If set to NO, the class list will
+# be sorted only by class name, not including the namespace part.
+# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES.
+# Note: This option applies only to the class list, not to the alphabetical
+# list.
+# The default value is: NO.
+
+SORT_BY_SCOPE_NAME     = NO
+
+# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper
+# type resolution of all parameters of a function it will reject a match between
+# the prototype and the implementation of a member function even if there is
+# only one candidate or it is obvious which candidate to choose by doing a
+# simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still
+# accept a match between prototype and implementation in such cases.
+# The default value is: NO.
+
+STRICT_PROTO_MATCHING  = NO
+
+# The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo
+# list. This list is created by putting \todo commands in the documentation.
+# The default value is: YES.
+
+GENERATE_TODOLIST      = YES
+
+# The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test
+# list. This list is created by putting \test commands in the documentation.
+# The default value is: YES.
+
+GENERATE_TESTLIST      = YES
+
+# The GENERATE_BUGLIST tag can be used to enable (YES) or disable (NO) the bug
+# list. This list is created by putting \bug commands in the documentation.
+# The default value is: YES.
+
+GENERATE_BUGLIST       = YES
+
+# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO)
+# the deprecated list. This list is created by putting \deprecated commands in
+# the documentation.
+# The default value is: YES.
+
+GENERATE_DEPRECATEDLIST= YES
+
+# The ENABLED_SECTIONS tag can be used to enable conditional documentation
+# sections, marked by \if <section_label> ... \endif and \cond <section_label>
+# ... \endcond blocks.
+
+ENABLED_SECTIONS       =
+
+# The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the
+# initial value of a variable or macro / define can have for it to appear in the
+# documentation. If the initializer consists of more lines than specified here
+# it will be hidden. Use a value of 0 to hide initializers completely. The
+# appearance of the value of individual variables and macros / defines can be
+# controlled using \showinitializer or \hideinitializer command in the
+# documentation regardless of this setting.
+# Minimum value: 0, maximum value: 10000, default value: 30.
+
+MAX_INITIALIZER_LINES  = 30
+
+# Set the SHOW_USED_FILES tag to NO to disable the list of files generated at
+# the bottom of the documentation of classes and structs. If set to YES, the
+# list will mention the files that were used to generate the documentation.
+# The default value is: YES.
+
+SHOW_USED_FILES        = YES
+
+# Set the SHOW_FILES tag to NO to disable the generation of the Files page. This
+# will remove the Files entry from the Quick Index and from the Folder Tree View
+# (if specified).
+# The default value is: YES.
+
+SHOW_FILES             = NO
+
+# Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces
+# page. This will remove the Namespaces entry from the Quick Index and from the
+# Folder Tree View (if specified).
+# The default value is: YES.
+
+SHOW_NAMESPACES        = YES
+
+# The FILE_VERSION_FILTER tag can be used to specify a program or script that
+# doxygen should invoke to get the current version for each file (typically from
+# the version control system). Doxygen will invoke the program by executing (via
+# popen()) the command command input-file, where command is the value of the
+# FILE_VERSION_FILTER tag, and input-file is the name of an input file provided
+# by doxygen. Whatever the program writes to standard output is used as the file
+# version. For an example see the documentation.
+
+FILE_VERSION_FILTER    =
+
+# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed
+# by doxygen. The layout file controls the global structure of the generated
+# output files in an output format independent way. To create the layout file
+# that represents doxygen's defaults, run doxygen with the -l option. You can
+# optionally specify a file name after the option, if omitted DoxygenLayout.xml
+# will be used as the name of the layout file.
+#
+# Note that if you run doxygen from a directory containing a file called
+# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE
+# tag is left empty.
+
+LAYOUT_FILE            =
+
+# The CITE_BIB_FILES tag can be used to specify one or more bib files containing
+# the reference definitions. This must be a list of .bib files. The .bib
+# extension is automatically appended if omitted. This requires the bibtex tool
+# to be installed. See also https://en.wikipedia.org/wiki/BibTeX for more info.
+# For LaTeX the style of the bibliography can be controlled using
+# LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the
+# search path. See also \cite for info how to create references.
+
+CITE_BIB_FILES         =
+
+#---------------------------------------------------------------------------
+# Configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+
+# The QUIET tag can be used to turn on/off the messages that are generated to
+# standard output by doxygen. If QUIET is set to YES this implies that the
+# messages are off.
+# The default value is: NO.
+
+QUIET                  = NO
+
+# The WARNINGS tag can be used to turn on/off the warning messages that are
+# generated to standard error (stderr) by doxygen. If WARNINGS is set to YES
+# this implies that the warnings are on.
+#
+# Tip: Turn warnings on while writing the documentation.
+# The default value is: YES.
+
+WARNINGS               = YES
+
+# If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate
+# warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag
+# will automatically be disabled.
+# The default value is: YES.
+
+WARN_IF_UNDOCUMENTED   = YES
+
+# If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for
+# potential errors in the documentation, such as not documenting some parameters
+# in a documented function, or documenting parameters that don't exist or using
+# markup commands wrongly.
+# The default value is: YES.
+
+WARN_IF_DOC_ERROR      = YES
+
+# This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that
+# are documented, but have no documentation for their parameters or return
+# value. If set to NO, doxygen will only warn about wrong or incomplete
+# parameter documentation, but not about the absence of documentation. If
+# EXTRACT_ALL is set to YES then this flag will automatically be disabled.
+# The default value is: NO.
+
+WARN_NO_PARAMDOC       = YES
+
+# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when
+# a warning is encountered.
+# The default value is: NO.
+
+WARN_AS_ERROR          = NO
+
+# The WARN_FORMAT tag determines the format of the warning messages that doxygen
+# can produce. The string should contain the $file, $line, and $text tags, which
+# will be replaced by the file and line number from which the warning originated
+# and the warning text. Optionally the format may contain $version, which will
+# be replaced by the version of the file (if it could be obtained via
+# FILE_VERSION_FILTER)
+# The default value is: $file:$line: $text.
+
+WARN_FORMAT            = "$file:$line: $text"
+
+# The WARN_LOGFILE tag can be used to specify a file to which warning and error
+# messages should be written. If left blank the output is written to standard
+# error (stderr).
+
+WARN_LOGFILE           = "../doxygen-warn.log"
+
+#---------------------------------------------------------------------------
+# Configuration options related to the input files
+#---------------------------------------------------------------------------
+
+# The INPUT tag is used to specify the files and/or directories that contain
+# documented source files. You may enter file names like myfile.cpp or
+# directories like /usr/src/myproject. Separate the files or directories with
+# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
+# Note: If this tag is empty the current directory is searched.
+
+INPUT                  = @LAMMPS_SOURCE_DIR@/utils.cpp                 \
+                         @LAMMPS_SOURCE_DIR@/utils.h                   \
+                         @LAMMPS_SOURCE_DIR@/library.cpp               \
+                         @LAMMPS_SOURCE_DIR@/library.h                 \
+                         @LAMMPS_SOURCE_DIR@/lammps.cpp                \
+                         @LAMMPS_SOURCE_DIR@/lammps.h                  \
+                         @LAMMPS_SOURCE_DIR@/pointers.h                \
+                         @LAMMPS_SOURCE_DIR@/lmptype.h                 \
+                         @LAMMPS_SOURCE_DIR@/atom.cpp                  \
+                         @LAMMPS_SOURCE_DIR@/atom.h                    \
+                         @LAMMPS_SOURCE_DIR@/input.cpp                 \
+                         @LAMMPS_SOURCE_DIR@/input.h                   \
+                         @LAMMPS_SOURCE_DIR@/tokenizer.cpp             \
+                         @LAMMPS_SOURCE_DIR@/tokenizer.h               \
+                         @LAMMPS_SOURCE_DIR@/text_file_reader.cpp      \
+                         @LAMMPS_SOURCE_DIR@/text_file_reader.h        \
+                         @LAMMPS_SOURCE_DIR@/potential_file_reader.cpp \
+                         @LAMMPS_SOURCE_DIR@/potential_file_reader.h   \
+                         @LAMMPS_SOURCE_DIR@/my_page.cpp               \
+                         @LAMMPS_SOURCE_DIR@/my_page.h                 \
+                         @LAMMPS_SOURCE_DIR@/my_pool_chunk.cpp         \
+                         @LAMMPS_SOURCE_DIR@/my_pool_chunk.h           \
+                         @LAMMPS_SOURCE_DIR@/math_eigen.h              \
+
+# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
+# directories that are symbolic links (a Unix file system feature) are excluded
+# from the input.
+# The default value is: NO.
+
+EXCLUDE_SYMLINKS       = YES
+
+#---------------------------------------------------------------------------
+# Configuration options related to output
+#---------------------------------------------------------------------------
+
+GENERATE_HTML          = NO
+GENERATE_LATEX         = NO
+GENERATE_XML           = YES
+XML_OUTPUT             = xml
+XML_PROGRAMLISTING     = YES
+XML_NS_MEMB_FILE_SCOPE = NO
+
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+
+# If the ENABLE_PREPROCESSING tag is set to YES, doxygen will evaluate all
+# C-preprocessor directives found in the sources and include files.
+# The default value is: YES.
+
+#ENABLE_PREPROCESSING   = YES
+ENABLE_PREPROCESSING   = NO
+
+# If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names
+# in the source code. If set to NO, only conditional compilation will be
+# performed. Macro expansion can be done in a controlled way by setting
+# EXPAND_ONLY_PREDEF to YES.
+# The default value is: NO.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
+
+MACRO_EXPANSION        = NO
+
+# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
+# the macro expansion is limited to the macros specified with the PREDEFINED and
+# EXPAND_AS_DEFINED tags.
+# The default value is: NO.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
+
+EXPAND_ONLY_PREDEF     = NO
+
+# If the SEARCH_INCLUDES tag is set to YES, the include files in the
+# INCLUDE_PATH will be searched if a #include is found.
+# The default value is: YES.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
+
+SEARCH_INCLUDES        = YES
+
+# The INCLUDE_PATH tag can be used to specify one or more directories that
+# contain include files that are not input files but should be processed by the
+# preprocessor.
+# This tag requires that the tag SEARCH_INCLUDES is set to YES.
+
+INCLUDE_PATH           =
+
+# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
+# patterns (like *.h and *.hpp) to filter out the header-files in the
+# directories. If left blank, the patterns specified with FILE_PATTERNS will be
+# used.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
+
+INCLUDE_FILE_PATTERNS  =
+
+# The PREDEFINED tag can be used to specify one or more macro names that are
+# defined before the preprocessor is started (similar to the -D option of e.g.
+# gcc). The argument of the tag is a list of macros of the form: name or
+# name=definition (no spaces). If the definition and the "=" are omitted, "=1"
+# is assumed. To prevent a macro definition from being undefined via #undef or
+# recursively expanded use the := operator instead of the = operator.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
+
+PREDEFINED             =
+
+# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
+# tag can be used to specify a list of macro names that should be expanded. The
+# macro definition that is found in the sources will be used. Use the PREDEFINED
+# tag if you want to use a different macro definition that overrules the
+# definition found in the source code.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
+
+EXPAND_AS_DEFINED      =
+
+# If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will
+# remove all references to function-like macros that are alone on a line, have
+# an all uppercase name, and do not end with a semicolon. Such function macros
+# are typically used for boiler-plate code, and will confuse the parser if not
+# removed.
+# The default value is: YES.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
+
+SKIP_FUNCTION_MACROS   = YES
+

doc/github-development-workflow.md

@@ -136,7 +136,8 @@ Here are some items to check:
     * string.h -> cstring
     * time.h -> ctime
     * Do NOT replace (as they are C++-11): `inttypes.h` and `stdint.h`.
-  * Code should follow the C++-98 standard. C++-11 is only accepted
+  * Code must follow the C++-11 standard. C++98-only is no longer accepted
+  * Code should use `nullptr` instead of `NULL` where applicable.
   in individual special purpose packages
   * indentation is 2 spaces per level
   * there should be NO tabs and no trailing whitespace (review the "checkstyle" test on pull requests)
@@ -145,6 +146,8 @@ Here are some items to check:
   Forward declarations should be used instead when possible.
   * iostreams should be avoided. LAMMPS uses stdio from the C-library.
   * use of STL in headers and class definitions should be avoided.
+  exception is <string>, but it won't need to be explicitly included
+  since pointers.h already includes it. so std::string can be used directly.
   * there MUST NOT be any "using namespace XXX;" statements in headers.
   * static class members should be avoided at all cost.
   * anything storing atom IDs should be using `tagint` and not `int`.
@@ -152,6 +155,8 @@ Here are some items to check:
   compiling LAMMPS with `-DLAMMPS_BIGBIG`.
   * when including both `lmptype.h` (and using defines or macros from it)
   and `mpi.h`, `lmptype.h` must be included first.
+  * see https://github.com/lammps/lammps/blob/master/doc/include-file-conventions.md
+  for general include file conventions and best practices
   * when pair styles are added, check if settings for flags like
   `single_enable`, `writedata`, `reinitflag`, `manybody_flag`
   and others are correctly set and supported.

doc/graphviz/.gitignore

@@ -0,0 +1,3 @@
+/*.png
+/*.svg
+/*.pdf

doc/graphviz/Makefile

@@ -0,0 +1,29 @@
+# Makefile for generating images with graphviz
+#
+BUILDDIR   = ${CURDIR}/..
+IMGDIR     = $(BUILDDIR)/src/JPG
+IMGSRC     = $(wildcard *.dot)
+IMGPNG     = $(IMGSRC:%.dot=$(IMGDIR)/%.png)
+
+HAS_DOT        = NO
+ifeq ($(shell which dot >/dev/null 2>&1; echo $$?), 0)
+HAS_DOT        = YES
+endif
+
+all:    $(IMGPNG)
+
+clean:
+	rm -f $(IMGSVG) $(IMGPDF) $(IMGPNG) *~
+
+ifeq ($(HAS_DOT),YES)
+$(IMGDIR)/%.png: %.dot
+	dot -Tpng -o $@ $<
+endif
+
+ifeq ($(HAS_DOT),NO)
+$(IMGDIR)/%.png: %.dot
+	@echo '###################################################'
+	@echo '# Need to install "graphviz" to regenerate graphs #'
+	@echo '###################################################'
+endif
+

doc/graphviz/lammps-classes.dot

@@ -0,0 +1,90 @@
+// LAMMPS Class topology
+digraph lammps {
+    rankdir="LR"
+    La [shape=circle label="LAMMPS"]
+    At [shape=box label="Atom" color=blue]
+    Ci [shape=box label="CiteMe"]
+    Co [shape=box label="Comm" color=blue]
+    Do [shape=box label="Domain" color=blue]
+    Er [shape=box label="Error" color=blue]
+    Fo [shape=box label="Force" color=blue]
+    Gr [shape=box label="Group" color=blue]
+    In [shape=box label="Input" color=blue]
+    Ko [shape=box label="KokkosLMP"]
+    Ak [shape=box label="AtomKK" color=blue]
+    Mk [shape=box label="MemoryKK" color=blue]
+    Me [shape=box label="Memory" color=blue]
+    Mo [shape=box label="Modify" color=blue]
+    Ne [shape=box label="Neighbor" color=blue]
+    Ou [shape=box label="Output" color=blue]
+    Py [shape=box label="Python" color=blue]
+    Up [shape=box label="Update" color=blue]
+    Un [shape=box label="Universe" color=blue]
+    Ti [shape=box label="Timer" color=blue]
+    Rg [label="Region" color=red]
+    Rb [shape=box label="RegionBlock"]
+    Rs [shape=box label="RegionSphere"]
+    Av [label="AtomVec" color=red]
+    It [label="Integrate" color=red]
+    Mi [label="Min" color=red]
+    Pa [label="Pair" color=red]
+    Bo [label="Bond" color=red]
+    An [label="Angle" color=red]
+    Di [label="Dihedral" color=red]
+    Im [label="Improper" color=red]
+    Ks [label="Kspace" color=red]
+    Du [label="Dump" color=red]
+    Fi [label="Fix" color=red]
+    Cp [label="Compute" color=red]
+    Th [label="Thermo"]
+    Va [label="Variable"]
+    Ew [shape=box label="Ewald"]
+    Pp [shape=box label="PPPM"]
+    Ff [label="FFT3d"]
+    Re [label="Remap"]
+    Gc [label="GridComm"]
+    Cb [shape=box label="CommBrick"]
+    Ct [shape=box label="CommTiled"]
+    Aa [shape=box label="AtomVecAtomic"]
+    Am [shape=box label="AtomVecMolecular"]
+    Lj [shape=box label="PairLJCut"]
+    Lo [shape=box label="PairLJCutOMP"]
+    Lg [shape=box label="PairLJCutGPU"]
+    Te [shape=box label="PairTersoff"]
+    Bh [shape=box label="BondHarmonic"]
+    Bf [shape=box label="BondFENE"]
+    Fa [shape=box label="FixAveTime"]
+    Fn [shape=box label="FixNVE"]
+    Fh [shape=box label="FixNH"]
+    Fp [shape=box label="FixNPT"]
+    Ft [shape=box label="FixNVT"]
+    Da [shape=box label="DumpAtom"]
+    Dc [shape=box label="DumpCustom"]
+    Dg [shape=box label="DumpCFG"]
+    Ve [shape=box label="Verlet"]
+    Rr [shape=box label="Respa"]
+    Po [shape=box label="PPPMOmp"]
+    La -> {At Ci Co Do Er Fo Gr In Ko Ak Mk Me Mo Ne Ou Py Ti Up Un} [penwidth=2]
+    Do -> {Rg} [penwidth=2]
+    Co -> {Cb Ct} [style=dashed penwidth=2]
+    Rg -> {Rb Rs} [style=dashed penwidth=2]
+    In -> Va [penwidth=2]
+    Mo -> {Fi Cp} [penwidth=2]
+    Fo -> {Pa Bo An Di Im Ks} [penwidth=2]
+    Ks -> {Ew Pp} [style=dashed penwidth=2]
+    Pp -> {Ff Re Gc} [penwidth=2]
+    Pp -> {Po} [style=dashed penwidth=2]
+    Up -> {It Mi} [penwidth=2]
+    It -> {Ve Rr} [style=dashed penwidth=2]
+    Ou -> {Du Th} [penwidth=2]
+    Du -> {Da Dc} [style=dashed penwidth=2]
+    Dc -> {Dg} [style=dashed penwidth=2]
+    At -> Av [penwidth=2]
+    Av -> {Aa Am} [style=dashed penwidth=2]
+    Pa -> {Lj Te} [style=dashed penwidth=2]
+    Lj -> {Lo Lg} [style=dashed penwidth=2]
+    Bo -> {Bh Bf} [style=dashed penwidth=2]
+    Fi -> {Fa Fn Fh} [style=dashed penwidth=2]
+    Fh -> {Fp Ft} [style=dashed penwidth=2]
+}
+

doc/graphviz/lammps-invoke-python.dot

@@ -0,0 +1,27 @@
+// LAMMPS -> Python
+digraph api {
+    rankdir="LR";
+    edge [constraint=false];
+    input [shape=box label="LAMMPS\nInput Script" height=1.5];
+    subgraph cluster0 {
+      style=filled;
+      color="#e5e5e5";
+      rank=same;
+      capi [shape=box style=filled height=1 color="#666666" fontcolor=white label="LAMMPS\nC Library API"];
+      instance [shape=box style=filled height=1 color="#3465a4" fontcolor=white label="LAMMPS\ninstance\n\n0x01abcdef"];
+      capi -> instance [dir=both];
+      label="LAMMPS Shared Library\nor LAMMPS Executable";
+    }
+    python [shape=box style=filled color="#4e9a06" fontcolor=white label="Python\nScript" height=1.5];
+    subgraph cluster1 {
+      style=filled;
+      color="#e5e5e5";
+      lammps [shape=box style=filled height=1 color="#729fcf" label="lammps\n\nptr: 0x01abcdef"];
+      label="LAMMPS Python Module";
+    }
+    input -> instance [constraint=true];
+    instance -> python [dir=both constraint=true];
+    python:e -> lammps:w [dir=both constraint=true];
+    lammps:s -> capi:e [dir=both label=ctypes constraint=true];
+}
+

doc/graphviz/pylammps-invoke-lammps.dot

@@ -0,0 +1,30 @@
+// PyLammps -> LAMMPS
+digraph api {
+    rankdir="LR";
+    edge [constraint=false];
+    python [shape=box style=filled color="#4e9a06" fontcolor=white label="Python\nScript" height=1.5];
+    subgraph cluster0 {
+      style=filled;
+      color="#e5e5e5";
+      height=1.5;
+      rank=same;
+      pylammps [shape=box style=filled height=1 color="#729fcf" label="(I)PyLammps"];
+      lammps [shape=box style=filled height=1 color="#729fcf" label="lammps\n\nptr: 0x01abcdef"];
+      pylammps -> lammps [dir=both];
+      label="LAMMPS Python Module";
+    }
+    subgraph cluster1 {
+      style=filled;
+      color="#e5e5e5";
+      height=1.5;
+      capi [shape=box style=filled height=1 color="#666666" fontcolor=white label="LAMMPS\nC Library API"];
+      instance [shape=box style=filled height=1 color="#3465a4" fontcolor=white label="LAMMPS\ninstance\n\n0x01abcdef"];
+      capi -> instance [dir=both constraint=true];
+      label="LAMMPS Shared Library";
+    }
+    python -> pylammps  [dir=both constraint=true];
+    lammps -> capi [dir=both label=ctypes constraint=true];
+
+    pylammps:e -> instance:ne [dir=back, style=dashed label="captured standard output"];
+}
+

doc/graphviz/python-invoke-lammps.dot

@@ -0,0 +1,24 @@
+// Python -> LAMMPS
+digraph api {
+    rankdir="LR";
+    python [shape=box style=filled color="#4e9a06" fontcolor=white label="Python\nScript" height=1.5];
+    subgraph cluster0 {
+      style=filled;
+      color="#e5e5e5";
+      height=1.5;
+      lammps [shape=box style=filled height=1 color="#729fcf" label="lammps\n\nptr: 0x01abcdef"];
+      label="LAMMPS Python Module";
+    }
+    subgraph cluster1 {
+      style=filled;
+      color="#e5e5e5";
+      height=1.5;
+      capi [shape=box style=filled height=1 color="#666666" fontcolor=white label="LAMMPS\nC Library API"];
+      instance [shape=box style=filled height=1 color="#3465a4" fontcolor=white label="LAMMPS\ninstance\n\n0x01abcdef"];
+      capi -> instance [dir=both];
+      label="LAMMPS Shared Library";
+    }
+    python -> lammps [dir=both];
+    lammps -> capi [dir=both,label=ctypes];
+}
+

doc/include-file-conventions.md

@@ -3,7 +3,7 @@
 This purpose of this document is to provide a point of reference
 for LAMMPS developers and contributors as to what include files
 and definitions to put where into LAMMPS source.
-Last change 2019-07-05
+Last change 2020-08-31
 
 ## Table of Contents
 
@@ -91,29 +91,31 @@ statements should follow the "include what you use" principle.
 
 Include files should be included in this order:
 * the header matching the implementation (`some_class.h` for file `some_class.cpp`)
-* mpi.h
-* system and library headers (anything that is using angular brackets; C-library headers first, then C++)
+* mpi.h  (only if needed)
 * LAMMPS local headers (preferably in alphabetical order)
+* system and library headers (anything that is using angular brackets; preferably in alphabetical order)
+* conditional include statements (i.e. anything bracketed with ifdefs)
 
 ### Special Cases and Exceptions
 
 #### pointers.h
 
-The `pointer.h` header file also includes `cstdio` and `lmptype.h`
-(and through it `stdint.h`, `intttypes.h`, cstdlib, and `climits`).
+The `pointer.h` header file also includes (in this order) `lmptype.h`,
+`mpi.h`, `cstddef`, `cstdio`, `string`, `utils.h`, and `fmt/format.h`
+and through `lmptype.h` indirectly also `climits`, `cstdlib`, `cinttypes`.
 This means any header including `pointers.h` can assume that `FILE`,
-`NULL`, `INT_MAX` are defined.
+`NULL`, `INT_MAX` are defined, and the may freely use the std::string
+for arguments. Corresponding implementation files do not need to include
+those headers.
 
 ## Tools
 
 The [Include What You Use tool](https://include-what-you-use.org/)
 can be used to provide supporting information about compliance with
-the rules listed here.  There are some limitations and the IWYU tool
-may give incorrect advice.  The tools is activated by setting the
-CMake variable `CMAKE_CXX_INCLUDE_WHAT_YOU_USE` variable to the
-path of the `include-what-you-use` command.  When activated, the
-tool will be run after each compilation and provide suggestions for
-which include files should be added or removed.
+the rules listed here.  Through setting `-DENABLE_IWYU=on` when running
+CMake, a custom build target is added that will enable recording
+the compilation commands and then run the `iwyu_tool` using the
+recorded compilation commands information when typing `make iwyu`.
 
 ## Legacy Code
 

doc/lammps.1

@@ -1,4 +1,4 @@
-.TH LAMMPS "24 August 2020" "2020-08-24"
+.TH LAMMPS "9 October 2020" "2020-10-09"
 .SH NAME
 .B LAMMPS
 \- Molecular Dynamics Simulator.

doc/requirements.txt

@@ -1,4 +0,0 @@
-Sphinx
-sphinxcontrib-spelling
-breathe
-Pygments

doc/src/Build.rst

@@ -8,7 +8,7 @@ Makefiles, Ninja, Xcode, Visual Studio, KDevelop, CodeBlocks and more).
 
 As an alternative you can download a package with pre-built executables
 or automated build trees as described on the :doc:`Install <Install>`
-doc page.
+page.
 
 .. toctree::
    :maxdepth: 1
@@ -20,5 +20,6 @@ doc page.
    Build_settings
    Build_package
    Build_extras
+   Build_manual
    Build_windows
    Build_development

doc/src/Build_basics.rst

@@ -8,7 +8,6 @@ CMake and make:
 * :ref:`Choice of compiler and compile/link options <compile>`
 * :ref:`Build the LAMMPS executable and library <exe>`
 * :ref:`Including and removing debug support <debug>`
-* :ref:`Build the LAMMPS documentation <doc>`
 * :ref:`Install LAMMPS after a build <install>`
 
 ----------
@@ -32,74 +31,80 @@ LAMMPS are also written with support for shared memory parallelization
 using the `OpenMP <https://en.wikipedia.org/wiki/OpenMP>`_ threading
 standard. A more detailed discussion of that is below.
 
-**CMake build**\ :
+.. tabs::
 
-.. code-block:: bash
+   .. tab:: CMake build
 
-   -D BUILD_MPI=value        # yes or no, default is yes if CMake finds MPI, else no
-   -D BUILD_OMP=value        # yes or no, default is yes if a compatible compiler is detected
-   -D LAMMPS_MACHINE=name    # name = mpi, serial, mybox, titan, laptop, etc
-                             # no default value
+      .. code-block:: bash
 
-The executable created by CMake (after running make) is named ``lmp`` unless
-the ``LAMMPS_MACHINE`` option is set.  When setting ``LAMMPS_MACHINE=name``
-the executable will be called ``lmp_name``.  Using ``BUILD_MPI=no`` will
-enforce building a serial executable using the MPI STUBS library.
+         -D BUILD_MPI=value        # yes or no, default is yes if CMake finds MPI, else no
+         -D BUILD_OMP=value        # yes or no, default is yes if a compatible compiler is detected
+         -D LAMMPS_MACHINE=name    # name = mpi, serial, mybox, titan, laptop, etc
+                                   # no default value
 
-**Traditional make**\ :
+      The executable created by CMake (after running make) is named
+      ``lmp`` unless the ``LAMMPS_MACHINE`` option is set.  When setting
+      ``LAMMPS_MACHINE=name`` the executable will be called
+      ``lmp_name``.  Using ``BUILD_MPI=no`` will enforce building a
+      serial executable using the MPI STUBS library.
 
-The build with traditional makefiles has to be done inside the source folder ``src``.
+   .. tab:: Traditional make
 
-.. code-block:: bash
+      The build with traditional makefiles has to be done inside the source folder ``src``.
 
-   make mpi                # parallel build, produces lmp_mpi using Makefile.mpi
-   make serial             # serial build, produces lmp_serial using Makefile/serial
-   make mybox              # uses Makefile.mybox to produce lmp_mybox
+      .. code-block:: bash
 
-Any ``make machine`` command will look up the make settings from a file
-``Makefile.machine`` in the folder ``src/MAKE`` or one of its
-sub-directories ``MINE``, ``MACHINES``, or ``OPTIONS``, create a folder
-``Obj_machine`` with all objects and generated files and an executable
-called ``lmp_machine``\ .  The standard parallel build with ``make mpi``
-assumes a standard MPI installation with MPI compiler wrappers where all
-necessary compiler and linker flags to get access and link with the
-suitable MPI headers and libraries are set by the wrapper programs.  For
-other cases or the serial build, you have to adjust the make file
-variables ``MPI_INC``, ``MPI_PATH``, ``MPI_LIB`` as well as ``CC`` and
-``LINK``\ .  To enable OpenMP threading usually a compiler specific flag
-needs to be added to the compile and link commands.  For the GNU
-compilers, this is ``-fopenmp``\ , which can be added to the ``CC`` and
-``LINK`` makefile variables.
+         make mpi                # parallel build, produces lmp_mpi using Makefile.mpi
+         make serial             # serial build, produces lmp_serial using Makefile/serial
+         make mybox              # uses Makefile.mybox to produce lmp_mybox
 
-For the serial build the following make variables are set (see src/MAKE/Makefile.serial):
+      Any ``make machine`` command will look up the make settings from a
+      file ``Makefile.machine`` in the folder ``src/MAKE`` or one of its
+      sub-directories ``MINE``, ``MACHINES``, or ``OPTIONS``, create a
+      folder ``Obj_machine`` with all objects and generated files and an
+      executable called ``lmp_machine``\ .  The standard parallel build
+      with ``make mpi`` assumes a standard MPI installation with MPI
+      compiler wrappers where all necessary compiler and linker flags to
+      get access and link with the suitable MPI headers and libraries
+      are set by the wrapper programs.  For other cases or the serial
+      build, you have to adjust the make file variables ``MPI_INC``,
+      ``MPI_PATH``, ``MPI_LIB`` as well as ``CC`` and ``LINK``\ .  To
+      enable OpenMP threading usually a compiler specific flag needs to
+      be added to the compile and link commands.  For the GNU compilers,
+      this is ``-fopenmp``\ , which can be added to the ``CC`` and
+      ``LINK`` makefile variables.
 
-.. code-block:: make
+      For the serial build the following make variables are set (see src/MAKE/Makefile.serial):
 
-   CC =            g++
-   LINK =          g++
-   MPI_INC =       -I../STUBS
-   MPI_PATH =      -L../STUBS
-   MPI_LIB =       -lmpi_stubs
+      .. code-block:: make
 
-You also need to build the STUBS library for your platform before making
-LAMMPS itself.  A ``make serial`` build does this for you automatically,
-otherwise, type ``make mpi-stubs`` from the src directory, or ``make``
-from the ``src/STUBS`` dir.  If the build fails, you may need to edit
-the ``STUBS/Makefile`` for your platform.  The stubs library does not
-provide MPI/IO functions required by some LAMMPS packages,
-e.g. ``MPIIO`` or ``USER-LB``, and thus is not compatible with those
-packages.
+         CC =            g++
+         LINK =          g++
+         MPI_INC =       -I../STUBS
+         MPI_PATH =      -L../STUBS
+         MPI_LIB =       -lmpi_stubs
 
-.. note::
+      You also need to build the STUBS library for your platform before
+      making LAMMPS itself.  A ``make serial`` build does this for you
+      automatically, otherwise, type ``make mpi-stubs`` from the src
+      directory, or ``make`` from the ``src/STUBS`` dir.  If the build
+      fails, you may need to edit the ``STUBS/Makefile`` for your
+      platform.  The stubs library does not provide MPI/IO functions
+      required by some LAMMPS packages, e.g. ``MPIIO`` or ``USER-LB``,
+      and thus is not compatible with those packages.
 
-   The file ``src/STUBS/mpi.c`` 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 ANSI-standard function ``clock()``
-   rolls over after an hour or so, and is therefore insufficient for
-   timing long LAMMPS simulations.
+      .. note::
 
-**MPI and OpenMP support info**\ :
+         The file ``src/STUBS/mpi.c`` 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
+         ANSI-standard function ``clock()`` rolls over after an hour or
+         so, and is therefore insufficient for timing long LAMMPS
+         simulations.
+
+MPI and OpenMP support in LAMMPS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 If you are installing MPI yourself to build a parallel LAMMPS
 executable, we recommend either MPICH or OpenMPI which are regularly
@@ -115,12 +120,12 @@ self-installed MPICH or OpenMPI, so you should study the provided
 documentation to find out how to build and link with it.
 
 The majority of OpenMP (threading) support in LAMMPS is provided by the
-``USER-OMP`` package; see the :doc:`Speed omp <Speed_omp>` doc page for
-details. The ``USER-INTEL`` package also includes OpenMP threading (it
-is compatible with ``USER-OMP`` and will usually fall back on styles
-from that package, if a ``USER-INTEL`` does not exist) and adds
-vectorization support when compiled with compatible compilers, in
-particular the Intel compilers on top of OpenMP. Also, the ``KOKKOS``
+``USER-OMP`` package; see the :doc:`Speed_omp`
+page for details. The ``USER-INTEL`` package also includes OpenMP
+threading (it is compatible with ``USER-OMP`` and will usually fall
+back on styles from that package, if a ``USER-INTEL`` does not exist)
+and adds vectorization support when compiled with compatible compilers,
+in particular the Intel compilers on top of OpenMP. Also, the ``KOKKOS``
 package can be compiled to include OpenMP threading.
 
 In addition, there are a few commands in LAMMPS that have native OpenMP
@@ -128,8 +133,8 @@ support included as well.  These are commands in the ``MPIIO``,
 ``SNAP``, ``USER-DIFFRACTION``, and ``USER-DPD`` packages.  In addition
 some packages support OpenMP threading indirectly through the libraries
 they interface to: e.g. ``LATTE``, ``KSPACE``, and ``USER-COLVARS``.
-See the :doc:`Packages details <Packages_details>` doc page for more
-info on these packages and the doc pages for their respective commands
+See the :doc:`Packages details <Packages_details>` page for more
+info on these packages and the pages for their respective commands
 for OpenMP threading info.
 
 For CMake, if you use ``BUILD_OMP=yes``, you can use these packages
@@ -145,18 +150,19 @@ please refer to its documentation.
 
 .. _default-none-issues:
 
-**OpenMP Compiler compatibility info**\ :
+OpenMP Compiler compatibility
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Some compilers do not fully support the ``default(none)`` directive
-and others (e.g. GCC version 9 and beyond, Clang version 10 and later)
-may implement strict OpenMP 4.0 and later semantics, which are incompatible
+Some compilers do not fully support the ``default(none)`` directive and
+others (e.g. GCC version 9 and beyond, Clang version 10 and later) may
+implement strict OpenMP 4.0 and later semantics, which are incompatible
 with the OpenMP 3.1 semantics used in LAMMPS for maximal compatibility
 with compiler versions in use.  If compilation with OpenMP enabled fails
-because of your compiler requiring strict OpenMP 4.0 semantic, you can
-change the behavior by adding ``-D LAMMPS_OMP_COMPAT=4`` to the ``LMP_INC``
-variable in your makefile, or add it to the command line while configuring
-with CMake. CMake will detect the suitable setting for the GNU, Clang,
-and Intel compilers.
+because of your compiler requiring strict OpenMP 4.0 semantics, you can
+change the behavior by adding ``-D LAMMPS_OMP_COMPAT=4`` to the
+``LMP_INC`` variable in your makefile, or add it to the command line
+while configuring with CMake.  LAMMPS will auto-detect a suitable setting
+for most GNU, Clang, and Intel compilers.
 
 ----------
 
@@ -185,135 +191,144 @@ for their compile/link environments, you can often access different
 compilers by simply loading the appropriate module before building
 LAMMPS.
 
-**CMake build**\ :
+.. tabs::
 
-By default CMake will use a compiler it finds according to internal
-preferences and it will add optimization flags appropriate to that
-compiler and any :doc:`accelerator packages <Speed_packages>` you have
-included in the build.
+   .. tab:: CMake build
 
-You can tell CMake to look for a specific compiler with setting CMake
-variables (listed below) during configuration.  For a few common
-choices, there are also presets in the ``cmake/presets`` folder.  For
-convenience, there is a ``CMAKE_TUNE_FLAGS`` variable that can be set to
-apply global compiler options (applied to compilation only), to be used
-for adding compiler or host specific optimization flags in addition to
-the "flags" variables listed below. You may also specify the
-corresponding ``CMAKE_*_FLAGS`` variables individually, if you want to
-experiment with alternate optimization flags.  You should specify all 3
-compilers, so that the (few) LAMMPS source files written in C or Fortran
-are built with a compiler consistent with the one used for the C++
-files:
+      By default CMake will use the compiler it finds according to
+      internal preferences and it will add optimization flags
+      appropriate to that compiler and any :doc:`accelerator packages
+      <Speed_packages>` you have included in the build.  CMake will
+      check if the detected or selected compiler is compatible with the
+      C++ support requirements of LAMMPS and stop with an error, if this
+      is not the case.
 
-.. code-block:: bash
+      You can tell CMake to look for a specific compiler with setting
+      CMake variables (listed below) during configuration.  For a few
+      common choices, there are also presets in the ``cmake/presets``
+      folder.  For convenience, there is a ``CMAKE_TUNE_FLAGS`` variable
+      that can be set to apply global compiler options (applied to
+      compilation only), to be used for adding compiler or host specific
+      optimization flags in addition to the "flags" variables listed
+      below. You may also specify the corresponding ``CMAKE_*_FLAGS``
+      variables individually, if you want to experiment with alternate
+      optimization flags.  You should specify all 3 compilers, so that
+      the (few) LAMMPS source files written in C or Fortran are built
+      with a compiler consistent with the one used for the C++ files:
 
-   -D CMAKE_CXX_COMPILER=name            # name of C++ compiler
-   -D CMAKE_C_COMPILER=name              # name of C compiler
-   -D CMAKE_Fortran_COMPILER=name        # name of Fortran compiler
+      .. code-block:: bash
 
-   -D CMAKE_CXX_FLAGS=string             # flags to use with C++ compiler
-   -D CMAKE_C_FLAGS=string               # flags to use with C compiler
-   -D CMAKE_Fortran_FLAGS=string         # flags to use with Fortran compiler
+         -D CMAKE_CXX_COMPILER=name            # name of C++ compiler
+         -D CMAKE_C_COMPILER=name              # name of C compiler
+         -D CMAKE_Fortran_COMPILER=name        # name of Fortran compiler
 
-A few example command lines are:
+         -D CMAKE_CXX_FLAGS=string             # flags to use with C++ compiler
+         -D CMAKE_C_FLAGS=string               # flags to use with C compiler
+         -D CMAKE_Fortran_FLAGS=string         # flags to use with Fortran compiler
 
-.. code-block:: bash
+      A few example command lines are:
 
-   # Building with GNU Compilers:
-   cmake ../cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DCMAKE_Fortran_COMPILER=gfortran
-   # Building with Intel Compilers:
-   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
+      .. code-block:: bash
 
-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
+         # Building with GNU Compilers:
+         cmake ../cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DCMAKE_Fortran_COMPILER=gfortran
+         # Building with Intel Compilers:
+         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
 
-In addition you can set ``CMAKE_TUNE_FLAGS`` to specifically add
-compiler flags to tune for optimal performance on given hosts. By
-default this variable is empty.
+      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.
 
-.. note::
+      In addition you can set ``CMAKE_TUNE_FLAGS`` to specifically add
+      compiler flags to tune for optimal performance on given hosts. By
+      default this variable is empty.
 
-   When the cmake command completes, it prints a summary to the screen
-   which compilers it is using and what flags and settings will be used
-   for the  compilation.  Note that if the top-level compiler is mpicxx,
-   it is simply a wrapper on a real compiler.  The underlying compiler
-   info is what CMake will try to determine and report.  You should check
-   to confirm you are using the compiler and optimization flags you want.
+      .. note::
 
-**Makefile.machine settings for traditional make**\ :
+         When the cmake command completes, it prints a summary to the
+         screen which compilers it is using and what flags and settings
+         will be used for the compilation.  Note that if the top-level
+         compiler is mpicxx, it is simply a wrapper on a real compiler.
+         The underlying compiler info is what CMake will try to
+         determine and report.  You should check to confirm you are
+         using the compiler and optimization flags you want.
 
-The "compiler/linker settings" section of a Makefile.machine lists
-compiler and linker settings for your C++ compiler, including
-optimization flags.  For a parallel build it is recommended to use
-``mpicxx`` or ``mpiCC``, since these compiler wrappers will include a
-variety of settings appropriate for your MPI installation and thus
-avoiding the guesswork of finding the right flags.
+   .. tab:: Makefile.machine settings for traditional make
 
-Parallel build (see ``src/MAKE/Makefile.mpi``):
+      The "compiler/linker settings" section of a Makefile.machine lists
+      compiler and linker settings for your C++ compiler, including
+      optimization flags.  For a parallel build it is recommended to use
+      ``mpicxx`` or ``mpiCC``, since these compiler wrappers will
+      include a variety of settings appropriate for your MPI
+      installation and thus avoiding the guesswork of finding the right
+      flags.
 
-.. code-block:: bash
+      Parallel build (see ``src/MAKE/Makefile.mpi``):
 
-   CC =            mpicxx
-   CCFLAGS =       -g -O3
-   LINK =          mpicxx
-   LINKFLAGS =     -g -O
+      .. code-block:: bash
 
-Serial build with GNU gcc (see ``src/MAKE/Makefile.serial``):
+         CC =            mpicxx
+         CCFLAGS =       -g -O3
+         LINK =          mpicxx
+         LINKFLAGS =     -g -O
 
-.. code-block:: make
+      Serial build with GNU gcc (see ``src/MAKE/Makefile.serial``):
 
-   CC =            g++
-   CCFLAGS =       -g -O3
-   LINK =          g++
-   LINKFLAGS =     -g -O
+      .. code-block:: make
 
+         CC =            g++
+         CCFLAGS =       -g -O3
+         LINK =          g++
+         LINKFLAGS =     -g -O
 
-.. note::
+      .. note::
 
-   If compilation stops with a message like the following:
+         If compilation stops with a message like the following:
 
-   .. code-block::
+         .. code-block::
 
-      g++ -g -O3  -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64    -I../STUBS     -c ../main.cpp
-      In file included from ../pointers.h:24:0,
-                 from ../input.h:17,
-                 from ../main.cpp:16:
-      ../lmptype.h:34:2: error: #error LAMMPS requires a C++11 (or later) compliant compiler. Enable C++11 compatibility or upgrade the compiler.
+            g++ -g -O3  -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64    -I../STUBS     -c ../main.cpp
+            In file included from ../pointers.h:24:0,
+                       from ../input.h:17,
+                       from ../main.cpp:16:
+            ../lmptype.h:34:2: error: #error LAMMPS requires a C++11 (or later) compliant compiler. Enable C++11 compatibility or upgrade the compiler.
 
-   then you have either an unsupported (old) compiler or you have to
-   turn on C++11 mode.  The latter applies to GCC 4.8.x shipped with
-   RHEL 7.x and CentOS 7.x.  For those compilers, you need to add the
-   ``-std=c++11`` flag.  Otherwise, you would have to install a newer
-   compiler that supports C++11; either as a binary package or through
-   compiling from source.
+         then you have either an unsupported (old) compiler or you have
+         to turn on C++11 mode.  The latter applies to GCC 4.8.x shipped
+         with RHEL 7.x and CentOS 7.x.  For those compilers, you need to
+         add the ``-std=c++11`` flag.  Otherwise, you would have to
+         install a newer compiler that supports C++11; either as a
+         binary package or through compiling from source.
 
-If you build LAMMPS with any :doc:`accelerator packages
-<Speed_packages>` included, there may be specific optimization flags
-that are either required or recommended to enable required features and
-to achieve optimal performance.  You need to include these in the
-CCFLAGS and LINKFLAGS settings above.  For details, see the individual
-package doc pages listed on the :doc:`Speed packages <Speed_packages>`
-doc page.  Or examine these files in the src/MAKE/OPTIONS directory.
-They correspond to each of the 5 accelerator packages and their hardware
-variants:
+         If you build LAMMPS with any :doc:`Speed_packages` included,
+         there may be specific compiler or linker flags that are either
+         required or recommended to enable required features and to
+         achieve optimal performance.  You need to include these in the
+         CCFLAGS and LINKFLAGS settings above.  For details, see the
+         documentation for the individual packages listed on the
+         :doc:`Speed_packages` page.  Or examine these files in the
+         src/MAKE/OPTIONS directory.  They correspond to each of the 5
+         accelerator packages and their hardware variants:
 
-.. code-block:: bash
+         .. code-block:: bash
 
-   Makefile.opt                   # OPT package
-   Makefile.omp                   # USER-OMP package
-   Makefile.intel_cpu             # USER-INTEL package for CPUs
-   Makefile.intel_coprocessor     # USER-INTEL package for KNLs
-   Makefile.gpu                   # GPU package
-   Makefile.kokkos_cuda_mpi       # KOKKOS package for GPUs
-   Makefile.kokkos_omp            # KOKKOS package for CPUs (OpenMP)
-   Makefile.kokkos_phi            # KOKKOS package for KNLs (OpenMP)
+            Makefile.opt                   # OPT package
+            Makefile.omp                   # USER-OMP package
+            Makefile.intel_cpu             # USER-INTEL package for CPUs
+            Makefile.intel_coprocessor     # USER-INTEL package for KNLs
+            Makefile.gpu                   # GPU package
+            Makefile.kokkos_cuda_mpi       # KOKKOS package for GPUs
+            Makefile.kokkos_omp            # KOKKOS package for CPUs (OpenMP)
+            Makefile.kokkos_phi            # KOKKOS package for KNLs (OpenMP)
 
 ----------
 
 .. _exe:
+.. _library:
 
 Build the LAMMPS executable and library
 ---------------------------------------
@@ -325,54 +340,59 @@ will then process commands provided via a file or from the console
 input.  The LAMMPS library can also be called from another application
 or a scripting language.  See the :doc:`Howto couple <Howto_couple>` doc
 page for more info on coupling LAMMPS to other codes.  See the
-:doc:`Python <Python_head>` doc page for more info on wrapping and
+:doc:`Python <Python_head>` page for more info on wrapping and
 running LAMMPS from Python via its library interface.
 
-**CMake build**\ :
+.. tabs::
 
-For CMake builds, you can select through setting CMake variables between
-building a shared or a static LAMMPS library and what kind of suffix is
-added to them (in case you want to concurrently install multiple variants
-of binaries with different settings). If none are set, defaults are applied.
+   .. tab:: CMake build
 
-.. code-block:: bash
+      For CMake builds, you can select through setting CMake variables
+      between building a shared or a static LAMMPS library and what kind
+      of suffix is added to them (in case you want to concurrently
+      install multiple variants of binaries with different settings). If
+      none are set, defaults are applied.
 
-   -D BUILD_SHARED_LIBS=value   # yes or no (default)
-   -D LAMMPS_MACHINE=name       # name = mpi, serial, mybox, titan, laptop, etc
-                                # no default value
+      .. code-block:: bash
 
-The compilation will always produce a LAMMPS library and an executable
-linked to it.  By default this will be a static library named
-``liblammps.a`` and an executable named ``lmp`` Setting
-``BUILD_SHARED_LIBS=yes`` will instead produce a shared library called
-``liblammps.so`` (or ``liblammps.dylib`` or ``liblammps.dll`` depending
-on the platform) If ``LAMMPS_MACHINE=name`` is set in addition, the name
-of the generated libraries will be changed to either
-``liblammps_name.a`` or ``liblammps_name.so``\ , respectively and the
-executable will be called ``lmp_name``.
+         -D BUILD_SHARED_LIBS=value   # yes or no (default)
+         -D LAMMPS_MACHINE=name       # name = mpi, serial, mybox, titan, laptop, etc
+                                      # no default value
 
-**Traditional make**\ :
+      The compilation will always produce a LAMMPS library and an
+      executable linked to it.  By default this will be a static library
+      named ``liblammps.a`` and an executable named ``lmp`` Setting
+      ``BUILD_SHARED_LIBS=yes`` will instead produce a shared library
+      called ``liblammps.so`` (or ``liblammps.dylib`` or
+      ``liblammps.dll`` depending on the platform) If
+      ``LAMMPS_MACHINE=name`` is set in addition, the name of the
+      generated libraries will be changed to either ``liblammps_name.a``
+      or ``liblammps_name.so``\ , respectively and the executable will
+      be called ``lmp_name``.
 
-With the traditional makefile based build process, the choice of
-the generated executable or library depends on the "mode" setting.
-Several options are available and ``mode=static`` is the default.
+   .. tab:: Traditional make
 
-.. code-block:: bash
+      With the traditional makefile based build process, the choice of
+      the generated executable or library depends on the "mode" setting.
+      Several options are available and ``mode=static`` is the default.
 
-   make machine               # build LAMMPS executable lmp_machine
-   make mode=static machine   # same as "make machine"
-   make mode=shared machine   # build LAMMPS shared lib liblammps_machine.so instead
+      .. code-block:: bash
 
-The "static" build will generate a static library called
-``liblammps_machine.a`` and an executable named ``lmp_machine``\ , while
-the "shared" build will generate a shared library
-``liblammps_machine.so`` instead and ``lmp_machine`` will be linked to
-it.  The build step will also create generic soft links, named
-``liblammps.a`` and ``liblammps.so``\ , which point to the specific
-``liblammps_machine.a/so`` files.
+         make machine               # build LAMMPS executable lmp_machine
+         make mode=static machine   # same as "make machine"
+         make mode=shared machine   # build LAMMPS shared lib liblammps_machine.so instead
 
-CMake and make info
-^^^^^^^^^^^^^^^^^^^
+      The "static" build will generate a static library called
+      ``liblammps_machine.a`` and an executable named ``lmp_machine``\ ,
+      while the "shared" build will generate a shared library
+      ``liblammps_machine.so`` instead and ``lmp_machine`` will be
+      linked to it.  The build step will also create generic soft links,
+      named ``liblammps.a`` and ``liblammps.so``\ , which point to the
+      specific ``liblammps_machine.a/so`` files.
+
+
+Additional information
+^^^^^^^^^^^^^^^^^^^^^^
 
 Note that for creating a shared library, all the libraries it depends on
 must be compiled to be compatible with shared libraries.  This should be
@@ -418,7 +438,7 @@ recommended to ensure the integrity of the system software installation.
 
 .. _debug:
 
-Excluding or removing debug support
+Including or removing debug support
 -----------------------------------
 
 By default the compilation settings will include the *-g* flag which
@@ -445,67 +465,6 @@ the debug information from the LAMMPS executable:
 
 ----------
 
-.. _doc:
-
-Build the LAMMPS documentation
-----------------------------------------
-
-The LAMMPS manual is written in `reStructuredText <rst_>`_ format which
-can be translated to different output format using the `Sphinx <sphinx_>`_
-document generator tool.  Currently the translation to HTML and PDF (via
-LaTeX) are supported.  For that to work a Python 3 interpreter and
-internet access is required.  For the documentation build a python
-based virtual environment is set up in the folder doc/docenv and various
-python packages are installed into that virtual environment via the pip
-tool.  The actual translation is then done via make commands.
-
-.. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html
-.. _sphinx: https://sphinx-doc.org
-
-Documentation make option
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The following make commands can be issued in the doc folder of the
-LAMMPS source distribution.
-
-.. code-block:: bash
-
-  make html          # create HTML doc pages in html directory
-  make pdf           # create Developer.pdf and Manual.pdf in this directory
-  make fetch         # fetch HTML and PDF files from LAMMPS web site
-  make clean         # remove all intermediate files
-  make clean-all     # reset the entire doc build environment
-  make anchor_check  # scan for duplicate anchor labels
-  make style_check   # check for complete and consistent style lists
-  make package_check # check for complete and consistent package lists
-  make spelling      # spell-check the manual
-
-Thus "make html" will create a "doc/html" directory with the HTML format
-manual pages so that you can browse them with a web browser locally on
-your system.
-
-.. note::
-
-   You can also download a tarball of the documentation for the
-   current LAMMPS version (HTML and PDF files), from the website
-   `download page <https://lammps.sandia.gov/download.html>`_.
-
-CMake build option
-^^^^^^^^^^^^^^^^^^
-
-It is also possible to create the HTML version of the manual within
-the :doc:`CMake build directory <Build_cmake>`.  The reason for this
-option is to include the installation of the HTML manual pages into
-the "install" step when installing LAMMPS after the CMake build via
-``make install``.  The documentation build is included in the default
-build target, but can also be requested independently with ``make doc``.
-
-.. code-block:: bash
-
-   -D BUILD_DOC=value       # yes or no (default)
-
-----------
-
 .. _tools:
 
 Build LAMMPS tools
@@ -514,27 +473,31 @@ Build LAMMPS tools
 Some tools described in :doc:`Auxiliary tools <Tools>` can be built directly
 using CMake or Make.
 
-CMake build
-^^^^^^^^^^^
+.. tabs::
 
-.. code-block:: bash
+   .. tab:: CMake build
 
-   -D BUILD_TOOLS=value       # yes or no (default)
+      .. code-block:: bash
 
-The generated binaries will also become part of the LAMMPS installation
-(see below).
+         -D BUILD_TOOLS=value         # yes or no (default)
+         -D BUILD_LAMMPS_SHELL=value  # yes or no (default)
 
-Traditional make
-^^^^^^^^^^^^^^^^
+      The generated binaries will also become part of the LAMMPS installation
+      (see below).
 
-.. code-block:: bash
+   .. tab:: Traditional make
 
-   cd lammps/tools
-   make all              # build all binaries of tools
-   make binary2txt       # build only binary2txt tool
-   make chain            # build only chain tool
-   make micelle2d        # build only micelle2d tool
-   make thermo_extract   # build only thermo_extract tool
+      .. code-block:: bash
+
+         cd lammps/tools
+         make all              # build all binaries of tools
+         make binary2txt       # build only binary2txt tool
+         make chain            # build only chain tool
+         make micelle2d        # build only micelle2d tool
+         make thermo_extract   # build only thermo_extract tool
+
+         cd lammps/tools/lammps-shell
+         make                  # build LAMMPS shell
 
 ----------
 
@@ -549,18 +512,19 @@ a globally visible place on your system, for others to access.  Note
 that you may need super-user privileges (e.g. sudo) if the directory
 you want to copy files to is protected.
 
-CMake build
-^^^^^^^^^^^
+.. tabs::
 
-.. code-block:: bash
+   .. tab:: CMake build
 
-   cmake -D CMAKE_INSTALL_PREFIX=path [options ...] ../cmake
-   make                        # perform make after CMake command
-   make install                # perform the installation into prefix
+      .. code-block:: bash
 
-Traditional make
-^^^^^^^^^^^^^^^^
+         cmake -D CMAKE_INSTALL_PREFIX=path [options ...] ../cmake
+         make                        # perform make after CMake command
+         make install                # perform the installation into prefix
 
-There is no "install" option in the ``src/Makefile`` for LAMMPS.  If
-you wish to do this you will need to first build LAMMPS, then manually
-copy the desired LAMMPS files to the appropriate system directories.
+   .. tab:: Traditional make
+
+      There is no "install" option in the ``src/Makefile`` for LAMMPS.
+      If you wish to do this you will need to first build LAMMPS, then
+      manually copy the desired LAMMPS files to the appropriate system
+      directories.

doc/src/Build_development.rst

@@ -28,6 +28,40 @@ variable VERBOSE set to 1:
 
 ----------
 
+.. _iwyu_processing:
+
+Report missing and unneeded '#include' statements
+-------------------------------------------------
+
+The conventions for how and when to use and order include statements in
+LAMMPS are `documented in a separate file <https://github.com/lammps/lammps/blob/master/doc/include-file-conventions.md>`_
+(also included in the source code distribution).  To assist with following
+these conventions one can use the `Include What You Use tool <https://include-what-you-use.org/>`_.
+This is still under development and for large and complex projects like LAMMPS
+there are some false positives, so suggested changes need to be verified manually.
+It is recommended to use at least version 0.14, which has much fewer incorrect
+reports than earlier versions.
+
+The necessary steps to generate the report can be enabled via a
+CMake variable:
+
+.. code-block:: bash
+
+   -D ENABLE_IWYU=value    # value = no (default) or yes
+
+This will check if the required binary (include-what-you-use or iwyu)
+and python script script (iwyu-tool or iwyu_tool or iwyu_tool.py) can
+be found in the path.  The analysis can then be started with:
+
+.. code-block:: bash
+
+   make iwyu
+
+This may first run some compilation, as the analysis is dependent
+on recording all commands required to do the compilation.
+
+----------
+
 .. _sanitizer:
 
 Address, Undefined Behavior, and Thread Sanitizer Support
@@ -37,14 +71,14 @@ Compilers such as GCC and Clang support generating instrumented binaries
 which use different sanitizer libraries to detect problems in the code
 during run-time. They can detect issues like:
 
- - `memory leaks <https://clang.llvm.org/docs/AddressSanitizer.html>`_
+ - `memory leaks <https://clang.llvm.org/docs/AddressSanitizer.html#memory-leak-detection>`_
  - `undefined behavior <https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html>`_
  - `data races <https://clang.llvm.org/docs/ThreadSanitizer.html>`_
 
 Please note that this kind of instrumentation usually comes with a
 performance hit (but much less than using tools like `Valgrind
-<https://valgrind.org>`_ with a more low level approach).  The to enable
-these features additional compiler flags need to be added to the
+<https://valgrind.org>`_ with a more low level approach).  To enable
+these features, additional compiler flags need to be added to the
 compilation and linking stages.  This is done through setting the
 ``ENABLE_SANITIZER`` variable during configuration. Examples:
 
@@ -77,7 +111,7 @@ error margin).  The status of this automated testing can be viewed on
 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 `YAML <http://pyyaml.org/>`_ library and development
+It requires the `PyYAML <http://pyyaml.org/>`_ library and development
 headers to compile and will download and compile a recent version of the
 `Googletest <https://github.com/google/googletest/>`_ C++ test framework
 for implementing the tests.
@@ -378,22 +412,22 @@ The images below illustrate how the data is presented.
 .. list-table::
 
       * - .. figure:: JPG/coverage-overview-top.png
-             :target: JPG/coverage-overview-top.png
+             :scale: 25%
 
           Top of the overview page
 
         - .. figure:: JPG/coverage-overview-manybody.png
-             :target: JPG/coverage-overview-manybody.png
+             :scale: 25%
 
           Styles with good coverage
 
         - .. figure:: JPG/coverage-file-top.png
-             :target: JPG/coverage-file-top.png
+             :scale: 25%
 
           Top of individual source page
 
         - .. figure:: JPG/coverage-file-branches.png
-             :target: JPG/coverage-file-branches.png
+             :scale: 25%
 
           Source page with branches
 

doc/src/Build_link.rst

@@ -4,11 +4,11 @@ Link LAMMPS as a library to another code
 LAMMPS is designed as a library of C++ objects that can be
 integrated into other applications including Python scripts.
 The files ``src/library.cpp`` and ``src/library.h`` define a
-C-style API for using LAMMPS as a library.  See the :doc:`Howto
-library <Howto_library>` page for a description of the interface
-and how to use it for your needs.
+C-style API for using LAMMPS as a library.  See the
+:doc:`Howto_library` page
+for a description of the interface and how to use it for your needs.
 
-The :doc:`Build basics <Build_basics>` doc page explains how to build
+The :doc:`Build_basics` page explains how to build
 LAMMPS as either a shared or static library.  This results in a file
 in the compilation folder called ``liblammps.a`` or ``liblammps_<name>.a``
 in case of building a static library.  In case of a shared library
@@ -41,42 +41,45 @@ The benefit of linking to a static library is, that the resulting
 executable is independent of that library since all required
 executable code from the library is copied into the calling executable.
 
-CMake build
-^^^^^^^^^^^
+.. tabs::
 
-This assumes that LAMMPS has been configured without setting a
-``LAMMPS_MACHINE`` name, installed with "make install", and the
-``PKG_CONFIG_PATH`` environment variable has been updated to include the
-``liblammps.pc`` file installed into the configured destination folder.
-The commands to compile and link a coupled executable are then:
+   .. tab:: CMake build
 
-.. code-block:: bash
+      This assumes that LAMMPS has been configured without setting a
+      ``LAMMPS_MACHINE`` name, installed with "make install", and the
+      ``PKG_CONFIG_PATH`` environment variable has been updated to
+      include the ``liblammps.pc`` file installed into the configured
+      destination folder.  The commands to compile and link a coupled
+      executable are then:
 
-   mpicc -c -O $(pkgconf liblammps --cflags) caller.c
-   mpicxx -o caller caller.o -$(pkgconf liblammps --libs)
+      .. code-block:: bash
 
-Traditional make
-^^^^^^^^^^^^^^^^
+         mpicc -c -O $(pkgconf liblammps --cflags) caller.c
+         mpicxx -o caller caller.o -$(pkgconf liblammps --libs)
 
-This assumes that LAMMPS has been compiled in the folder
-``${HOME}/lammps/src`` with "make mpi". The commands to compile and link
-a coupled executable are then:
+   .. tab:: Traditional make
 
-.. code-block:: bash
+      This assumes that LAMMPS has been compiled in the folder
+      ``${HOME}/lammps/src`` with "make mpi". The commands to compile
+      and link a coupled executable are then:
 
-   mpicc -c -O -I${HOME}/lammps/src caller.c
-   mpicxx -o caller caller.o -L${HOME}/lammps/src -llammps_mpi
+      .. code-block:: bash
 
-The *-I* argument is the path to the location of the ``library.h``
-header file containing the interface to the LAMMPS C-style library
-interface.  The *-L* argument is the path to where the ``liblammps_mpi.a``
-file is located.  The *-llammps_mpi* argument is shorthand for telling the
-compiler to link the file ``liblammps_mpi.a``.  If LAMMPS has been
-built as a shared library, then the linker will use ``liblammps_mpi.so``
-instead.  If both files are available, the linker will usually prefer
-the shared library.  In case of a shared library, you may need to update
-the ``LD_LIBRARY_PATH`` environment variable or running the ``caller``
-executable will fail since it cannot find the shared library at runtime.
+         mpicc -c -O -I${HOME}/lammps/src caller.c
+         mpicxx -o caller caller.o -L${HOME}/lammps/src -llammps_mpi
+
+      The *-I* argument is the path to the location of the ``library.h``
+      header file containing the interface to the LAMMPS C-style library
+      interface.  The *-L* argument is the path to where the
+      ``liblammps_mpi.a`` file is located.  The *-llammps_mpi* argument
+      is shorthand for telling the compiler to link the file
+      ``liblammps_mpi.a``.  If LAMMPS has been built as a shared
+      library, then the linker will use ``liblammps_mpi.so`` instead.
+      If both files are available, the linker will usually prefer the
+      shared library.  In case of a shared library, you may need to
+      update the ``LD_LIBRARY_PATH`` environment variable or running the
+      ``caller`` executable will fail since it cannot find the shared
+      library at runtime.
 
 However, it is only as simple as shown above for the case of a plain
 LAMMPS library without any optional packages that depend on libraries
@@ -84,61 +87,62 @@ LAMMPS library without any optional packages that depend on libraries
 need to include all flags, libraries, and paths for the coupled
 executable, that are also required to link the LAMMPS executable.
 
-CMake build
-^^^^^^^^^^^
+.. tabs::
 
-When using CMake, additional libraries with sources in the lib folder
-are built, but not included in ``liblammps.a`` and (currently) not
-installed with ``make install`` and not included in the ``pkgconfig``
-configuration file.  They can be found in the top level build folder,
-but you have to determine the necessary link flags manually.  It is
-therefore recommended to either use the traditional make procedure to
-build and link with a static library or build and link with a shared
-library instead.
+   .. tab:: CMake build
 
-Traditional make
-^^^^^^^^^^^^^^^^
+      When using CMake, additional libraries with sources in the lib
+      folder are built, but not included in ``liblammps.a`` and
+      (currently) not installed with ``make install`` and not included
+      in the ``pkgconfig`` configuration file.  They can be found in the
+      top level build folder, but you have to determine the necessary
+      link flags manually.  It is therefore recommended to either use
+      the traditional make procedure to build and link with a static
+      library or build and link with a shared library instead.
 
-After you have compiled a static LAMMPS library using the conventional
-build system for example with "make mode=static serial". And you also
-have installed the ``POEMS`` package after building its bundled library
-in ``lib/poems``. Then the commands to build and link the coupled executable
-change to:
+   .. tab:: Traditional make
 
-.. code-block:: bash
+      After you have compiled a static LAMMPS library using the
+      conventional build system for example with "make mode=static
+      serial". And you also have installed the ``POEMS`` package after
+      building its bundled library in ``lib/poems``. Then the commands
+      to build and link the coupled executable change to:
 
-   gcc -c -O -I${HOME}/lammps/src/STUBS -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
+      .. code-block:: bash
 
-Note, that you need to link with ``g++`` instead of ``gcc`` even if you have
-written your code in C, since LAMMPS itself is C++ code.  You can display the
-currently applied settings for building LAMMPS for the "serial" machine target
-by using the command:
+         gcc -c -O -I${HOME}/lammps/src/STUBS -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
 
-.. code-block:: bash
+      Note, that you need to link with ``g++`` instead of ``gcc`` even
+      if you have written your code in C, since LAMMPS itself is C++
+      code.  You can display the currently applied settings for building
+      LAMMPS for the "serial" machine target by using the command:
 
-   make mode=print serial
+      .. code-block:: bash
 
-Which should output something like:
+         make mode=print serial
 
-.. code-block:: bash
+      Which should output something like:
 
-   # Compiler:
-   CXX=g++
-   # Linker:
-   LD=g++
-   # Compilation:
-   CXXFLAGS=-g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I${HOME}/compile/lammps/lib/poems -I${HOME}/compile/lammps/src/STUBS
-   # Linking:
-   LDFLAGS=-g -O
-   # Libraries:
-   LDLIBS=-L${HOME}/compile/lammps/src -llammps_serial -L${HOME}/compile/lammps/lib/poems -L${HOME}/compile/lammps/src/STUBS -lpoems -lmpi_stubs
+      .. code-block:: bash
 
-From this you can gather the necessary paths and flags.  With
-makefiles for other *machine* configurations you need to do the
-equivalent and replace "serial" with the corresponding "machine" name
-of the makefile.
+         # Compiler:
+         CXX=g++
+         # Linker:
+         LD=g++
+         # Compilation:
+         CXXFLAGS=-g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I${HOME}/compile/lammps/lib/poems -I${HOME}/compile/lammps/src/STUBS
+         # Linking:
+         LDFLAGS=-g -O
+         # Libraries:
+         LDLIBS=-L${HOME}/compile/lammps/src -llammps_serial -L${HOME}/compile/lammps/lib/poems -L${HOME}/compile/lammps/src/STUBS -lpoems -lmpi_stubs
+
+      From this you can gather the necessary paths and flags.  With
+      makefiles for other *machine* configurations you need to do the
+      equivalent and replace "serial" with the corresponding "machine"
+      name of the makefile.
 
 Link with LAMMPS as a shared library
 ------------------------------------
@@ -151,35 +155,36 @@ linking the calling executable.  Only the *-I* flags are needed.  So the
 example case from above of the serial version static LAMMPS library with
 the POEMS package installed becomes:
 
-CMake build
-^^^^^^^^^^^
+.. tabs::
 
-The commands with a shared LAMMPS library compiled with the CMake
-build process are the same as for the static library.
+   .. tab:: CMake build
 
-.. code-block:: bash
+      The commands with a shared LAMMPS library compiled with the CMake
+      build process are the same as for the static library.
 
-   mpicc -c -O $(pkgconf liblammps --cflags) caller.c
-   mpicxx -o caller caller.o -$(pkgconf --libs)
+      .. code-block:: bash
 
-Traditional make
-^^^^^^^^^^^^^^^^
+         mpicc -c -O $(pkgconf liblammps --cflags) caller.c
+         mpicxx -o caller caller.o -$(pkgconf --libs)
 
-The commands with a shared LAMMPS library compiled with the
-traditional make build using ``make mode=shared serial`` becomes:
+   .. tab:: Traditional make
 
-.. code-block:: bash
+      The commands with a shared LAMMPS library compiled with the
+      traditional make build using ``make mode=shared serial`` becomes:
 
-   gcc -c -O -I${HOME}/lammps/src/STUBS -I${HOME}/lammps/src -caller.c
-   g++ -o caller caller.o -L${HOME}/lammps/src -llammps_serial
+      .. code-block:: bash
 
-*Locating liblammps.so at runtime*\ :
+         gcc -c -O -I${HOME}/lammps/src/STUBS -I${HOME}/lammps/src -caller.c
+         g++ -o caller caller.o -L${HOME}/lammps/src -llammps_serial
 
-However, now the ``liblammps.so`` file is required at runtime and needs
-to be in a folder, where the shared linker program of the operating
-system can find it.  This would be either a folder like ``/usr/local/lib64``
-or ``${HOME}/.local/lib64`` or a folder pointed to by the ``LD_LIBRARY_PATH``
-environment variable. You can type
+Locating liblammps.so at runtime
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Unlike with a static link, now the ``liblammps.so`` file is required at
+runtime and needs to be in a folder, where the shared linker program of
+the operating system can find it.  This would be either a folder like
+``/usr/local/lib64`` or ``${HOME}/.local/lib64`` or a folder pointed to
+by the ``LD_LIBRARY_PATH`` environment variable. You can type
 
 .. code-block:: bash
 
@@ -187,9 +192,10 @@ environment variable. You can type
 
 to see what directories are in that list.
 
-Or you can add the LAMMPS src directory (or the directory you performed
-a CMake style build in) to your ``LD_LIBRARY_PATH``, so that the current
-version of the shared library is always available to programs that use it.
+Or you can add the LAMMPS src directory or the directory you performed a
+CMake style build in to your ``LD_LIBRARY_PATH`` environment variable,
+so that the current version of the shared library is always available to
+programs that use it.
 
 For the Bourne or Korn shells (/bin/sh, /bin/ksh, /bin/bash etc.), you
 would add something like this to your ``${HOME}/.profile`` file:

doc/src/Build_make.rst

@@ -27,17 +27,17 @@ additional tools to be available and functioning.
   * a few shell utilities: ``ls``, ``mv``, ``ln``, ``rm``, ``grep``, ``sed``, ``tr``, ``cat``, ``touch``, ``diff``, ``dirname``
   * python (optional, required for ``make lib-<pkg>`` in the src folder).
     python scripts are currently tested with python 2.7 and 3.6. The procedure
-    for :doc:`building the documentation <Manual_build>` requires python 3.
+    for :doc:`building the documentation <Build_manual>` requires python 3.5 or later.
 
 Getting started
 ^^^^^^^^^^^^^^^
 
 To include LAMMPS packages (i.e. optional commands and styles) you must
 enable (or "install") them first, as discussed on the :doc:`Build
-package <Build_package>` doc page.  If a packages requires (provided or
+package <Build_package>` page.  If a packages requires (provided or
 external) libraries, you must configure and build those libraries
 **before** building LAMMPS itself and especially **before** enabling
-such a package with ``make yes-<package>``.  Building :doc:`LAMMPS with
+such a package with ``make yes-<package>``.  :doc:`Building LAMMPS with
 CMake <Build_cmake>` can automate much of this for many types of
 machines, especially workstations, desktops, and laptops, so we suggest
 you try it first when building LAMMPS in those cases.

doc/src/Build_manual.rst

@@ -1,5 +1,5 @@
-Building the LAMMPS manual
-**************************
+Build the LAMMPS documentation
+==============================
 
 Depending on how you obtained LAMMPS and whether you have built the
 manual yourself, this directory has a number of sub-directories and
@@ -14,12 +14,10 @@ files. Here is a list with descriptions:
    lammps.1         # man page for the lammps command
    msi2lmp.1        # man page for the msi2lmp command
    Manual.pdf       # large PDF version of entire manual
-   Developer.pdf    # small PDF with info about how LAMMPS is structured
    LAMMPS.epub      # Manual in ePUB e-book format
    LAMMPS.mobi      # Manual in MOBI e-book format
    docenv           # virtualenv folder for processing the manual sources
    doctrees         # temporary data from processing the manual
-   mathjax          # code and fonts for rendering math in html
    doxygen          # doxygen configuration and output
    .gitignore       # list of files and folders to be ignored by git
    doxygen-warn.log # logfile with warnings from running doxygen
@@ -34,34 +32,59 @@ and PDF files are not included.  Instead you need to create them, in one
 of two ways:
 
 a. You can "fetch" the current HTML and PDF files from the LAMMPS web
-   site.  Just type ``make fetch``.  This should download a html_www
-   directory and Manual_www.pdf/Developer_www.pdf files.  Note that if
-   new LAMMPS features have been added more recently than the date of
-   your LAMMPS version, the fetched documentation will include those
-   changes (but your source code will not, unless you update your local
-   repository).
+   site.  Just type ``make fetch``.  This should download a ``html_www``
+   directory and a ``Manual_www.pdf`` file.  Note that if new LAMMPS features
+   have been added more recently than the date of your LAMMPS version, the
+   fetched documentation will include those changes (but your source code
+   will not, unless you update your local repository).
 
 b. You can build the HTML or PDF files yourself, by typing ``make html``
-   or ``make pdf``.  This requires various tools and files.  Some of them
-   have to be installed (more on that below). For the rest the build
-   process will attempt to download and install them into a python
-   virtual environment and local folders.  This download is required
-   only once, unless you type ``make clean-all``.  After that, viewing and
-   processing of the documentation can be done without internet access.
+   or ``make pdf`` in the ``doc`` folder.  This requires various tools
+   and files.  Some of them have to be installed (see below).  For the
+   rest the build process will attempt to download and install them into
+   a python virtual environment and local folders.
 
-----------
+A current version of the manual (latest patch release, aka unstable
+branch) is is available online at:
+`https://lammps.sandia.gov/doc/Manual.html
+<https://lammps.sandia.gov/doc/Manual.html>`_ A version of the manual
+corresponding to the ongoing development (aka master branch) is
+available online at: `https://docs.lammps.org/
+<https://docs.lammps.org/>`_
 
-The generation of all documentation is managed by the Makefile in the
-doc directory. The following documentation related make commands are
-available:
+Build using GNU make
+--------------------
+
+The LAMMPS manual is written in `reStructuredText <rst_>`_ format which
+can be translated to different output format using the `Sphinx
+<sphinx_>`_ document generator tool.  It also incorporates programmer
+documentation extracted from the LAMMPS C++ sources through the `Doxygen
+<https://doxygen.nl>`_ program.  Currently the translation to HTML, PDF
+(via LaTeX), ePUB (for many e-book readers) and MOBI (for Amazon Kindle
+readers) are supported.  For that to work a Python 3 interpreter, the
+``doxygen`` tools and internet access to download additional files and
+tools are required.  This download is usually only required once or
+after the documentation folder is returned to a pristine state with
+``make clean-all``.
+
+.. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html
+.. _sphinx: https://www.sphinx-doc.org
+
+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/>`_ and the
+`Polyfill <https://polyfill.io/>`_ JavaScript engines need to be downloaded.
+
+The actual translation is then done via ``make`` commands in the doc
+folder.  The following ``make`` commands are available:
 
 .. code-block:: bash
 
    make html          # generate HTML in html dir using Sphinx
-   make pdf           # generate 2 PDF files (Manual.pdf,Developer.pdf)
-                      #   in doc dir via htmldoc and pdflatex
-   make fetch         # fetch HTML doc pages and 2 PDF files from web site
-                      #   as a tarball and unpack into html dir and 2 PDFs
+   make pdf           # generate PDF  as Manual.pdf using Sphinx and pdflatex
+   make fetch         # fetch HTML pages and PDF files from LAMMPS web site
+                      #  and unpack into the html_www folder and Manual_www.pdf
    make epub          # generate LAMMPS.epub in ePUB format using Sphinx
    make mobi          # generate LAMMPS.mobi in MOBI format using ebook-convert
 
@@ -75,65 +98,79 @@ available:
 
 ----------
 
-Installing prerequisites for HTML build
-=======================================
+Build using CMake
+-----------------
+
+It is also possible to create the HTML version (and **only** the HTML
+version) of the manual within the :doc:`CMake build directory
+<Build_cmake>`.  The reason for this option is to include the
+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``.
+
+.. code-block:: bash
+
+   -D BUILD_DOC=value       # yes or no (default)
+
+----------
+
+Prerequisites for HTML
+----------------------
 
 To run the HTML documentation build toolchain, python 3, git, doxygen,
 and virtualenv have to be installed locally.  Here are instructions for
 common setups:
 
-Ubuntu
-------
+.. tabs::
 
-.. code-block:: bash
+   .. tab:: Ubuntu
 
-   sudo apt-get install python-virtualenv git doxygen
+      .. code-block:: bash
 
-Fedora (up to version 21) and Red Hat Enterprise Linux or CentOS (up to version 7.x)
-------------------------------------------------------------------------------------
+         sudo apt-get install python-virtualenv git doxygen
 
-.. code-block:: bash
+   .. tab:: RHEL or CentOS (Version 7.x)
 
-   sudo yum install python3-virtualenv git doxygen
+      .. code-block:: bash
 
-Fedora (since version 22)
--------------------------
+         sudo yum install python3-virtualenv git doxygen
 
-.. code-block:: bash
+   .. tab:: Fedora or RHEL/CentOS (8.x or later)
 
-   sudo dnf install python3-virtualenv git doxygen
+      .. code-block:: bash
 
-MacOS X
--------
+         sudo dnf install python3-virtualenv git doxygen
 
-Python 3
-^^^^^^^^
+   .. tab:: MacOS X
 
-Download the latest Python 3 MacOS X package from
-`https://www.python.org <https://www.python.org>`_
-and install it.  This will install both Python 3
-and pip3.
+      *Python 3*
 
-virtualenv
-^^^^^^^^^^
+      Download the latest Python 3 MacOS X package from
+      `https://www.python.org <https://www.python.org>`_ and install it.
+      This will install both Python 3 and pip3.
 
-Once Python 3 is installed, open a Terminal and type
+      *virtualenv*
 
-.. code-block:: bash
+      Once Python 3 is installed, open a Terminal and type
 
-   pip3 install virtualenv
+      .. code-block:: bash
 
-This will install virtualenv from the Python Package Index.
+         pip3 install virtualenv
 
-Installing prerequisites for PDF build
-======================================
+      This will install virtualenv from the Python Package Index.
+
+Prerequisites for PDF
+---------------------
 
 In addition to the tools needed for building the HTML format manual,
 a working LaTeX installation with support for PDFLaTeX and a selection
-of LaTeX styles/packages are required.
+of LaTeX styles/packages are required.  To run the PDFLaTeX translation
+the ``latexmk`` script needs to be installed as well.
 
-Installing prerequisites for e-book reader builds
-=================================================
+Prerequisites for ePUB and MOBI
+-------------------------------
 
 In addition to the tools needed for building the HTML format manual,
 a working LaTeX installation with a few add-on LaTeX packages
@@ -150,12 +187,12 @@ files, so you could download and view the PDF version as an alternative.
 
 
 Instructions for Developers
-===========================
+---------------------------
 
 When adding new styles or options to the LAMMPS code, corresponding
 documentation is required and either existing files in the ``src``
-folder need to be updated or new files added. These files are written
-in `reStructuredText <rst_>`_ markup for translation with the Sphinx tool.
+folder need to be updated or new files added. These files are written in
+`reStructuredText <rst_>`_ markup for translation with the Sphinx tool.
 
 Before contributing any documentation, please check that both the HTML
 and the PDF format documentation can translate without errors. Please also

doc/src/Build_package.rst

@@ -7,7 +7,7 @@ rigid-body constraints are in packages.  In the src directory, each
 package is a sub-directory with the package name in capital letters.
 
 An overview of packages is given on the :doc:`Packages <Packages>` doc
-page.  Brief overviews of each package are on the :doc:`Packages details <Packages_details>` doc page.
+page.  Brief overviews of each package are on the :doc:`Packages details <Packages_details>` page.
 
 When building LAMMPS, you can choose to include or exclude each
 package.  In general there is no need to include a package if you
@@ -25,7 +25,7 @@ when building that executable.
 For the majority of packages, if you follow the single step below to
 include it, you can then build LAMMPS exactly the same as you would
 without any packages installed.  A few packages may require additional
-steps, as explained on the :doc:`Build extras <Build_extras>` doc page.
+steps, as explained on the :doc:`Build extras <Build_extras>` page.
 
 These links take you to the extra instructions for those select
 packages:
@@ -45,91 +45,92 @@ packages:
 The mechanism for including packages is simple but different for CMake
 versus make.
 
-CMake build
-^^^^^^^^^^^
+.. tabs::
 
-.. code-block:: csh
+   .. tab:: CMake build
 
-   -D PKG_NAME=value          # yes or no (default)
+      .. code-block:: csh
 
-Examples:
+         -D PKG_NAME=value          # yes or no (default)
 
-.. code-block:: csh
+      Examples:
 
-   -D PKG_MANYBODY=yes
-   -D PKG_USER-INTEL=yes
+      .. code-block:: csh
 
-All standard and user packages are included the same way.  Note that
-USER packages have a hyphen between USER and the rest of the package
-name, not an underscore.
+         -D PKG_MANYBODY=yes
+         -D PKG_USER-INTEL=yes
 
-See the shortcut section below for how to install many packages at
-once with CMake.
+      All standard and user packages are included the same way.  Note
+      that USER packages have a hyphen between USER and the rest of the
+      package name, not an underscore.
+
+      See the shortcut section below for how to install many packages at
+      once with CMake.
+
+      .. note::
+
+         If you switch between building with CMake and make builds, no
+         packages in the src directory can be installed when you invoke
+         ``cmake``.  CMake will give an error if that is not the case,
+         indicating how you can un-install all packages in the src dir.
+
+   .. tab:: Traditional make
+
+      .. code-block:: bash
+
+         cd lammps/src
+         make ps                    # check which packages are currently installed
+         make yes-name              # install a package with name
+         make no-name               # un-install a package with name
+         make mpi                   # build LAMMPS with whatever packages are now installed
+
+      Examples:
+
+      .. code-block:: bash
+
+         make no-rigid
+         make yes-user-intel
+
+      All standard and user packages are included the same way.
+
+      See the shortcut section below for how to install many packages at
+      once with make.
+
+      .. note::
+
+         You must always re-build LAMMPS (via make) after installing or
+         un-installing a package, for the action to take effect. The
+         included dependency tracking will make certain only files that
+         are required to be rebuilt are recompiled.
+
+      .. note::
+
+         You cannot install or un-install packages and build LAMMPS in a
+         single make command with multiple targets, e.g. ``make
+         yes-colloid mpi``.  This is because the make procedure creates
+         a list of source files that will be out-of-date for the build
+         if the package configuration changes within the same command.
+         You can include or exclude multiple packages in a single make
+         command, e.g. ``make yes-colloid no-manybody``.
+
+
+Information for both build systems
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Almost all packages can be included or excluded in a LAMMPS build,
+independent of the other packages.  However, some packages include files
+derived from files in other packages.  LAMMPS checks for this and does
+the right thing.  Individual files are only included if their
+dependencies are already included.  Likewise, if a package is excluded,
+other files dependent on that package are also excluded.
 
 .. note::
 
-   If you toggle back and forth between building with CMake vs
-   make, no packages in the src directory can be installed when you
-   invoke cmake.  CMake will give an error if that is not the case,
-   indicating how you can un-install all packages in the src dir.
-
-Traditional make
-^^^^^^^^^^^^^^^^
-
-.. code-block:: bash
-
-   cd lammps/src
-   make ps                    # check which packages are currently installed
-   make yes-name              # install a package with name
-   make no-name               # un-install a package with name
-   make mpi                   # build LAMMPS with whatever packages are now installed
-
-Examples:
-
-.. code-block:: bash
-
-   make no-rigid
-   make yes-user-intel
-
-All standard and user packages are included the same way.
-
-See the shortcut section below for how to install many packages at
-once with make.
-
-.. note::
-
-   You must always re-build LAMMPS (via make) after installing or
-   un-installing a package, for the action to take effect.
-
-.. note::
-
-   You cannot install or un-install packages and build LAMMPS in a
-   single make command with multiple targets, e.g. make yes-colloid mpi.
-   This is because the make procedure creates a list of source files that
-   will be out-of-date for the build if the package configuration changes
-   within the same command.  You can include or exclude multiple packages
-   in a single make command, e.g. make yes-colloid no-manybody.
-
-CMake and make info
-^^^^^^^^^^^^^^^^^^^
-
-Any package can be included or excluded in a LAMMPS build, independent
-of all other packages.  However, some packages include files derived
-from files in other packages.  LAMMPS checks for this and does the
-right thing.  Individual files are only included if their dependencies
-are already included.  Likewise, if a package is excluded, other files
-dependent on that package are also excluded.
-
-When you download a LAMMPS tarball or download LAMMPS source files
-from the git repository, no packages are pre-installed in the
-src directory.
-
-.. note::
-
-   Prior to Aug 2018, if you downloaded a tarball, 3 packages
-   (KSPACE, MANYBODY, MOLECULE) were pre-installed in the src directory.
-   That is no longer the case, so that CMake will build as-is without the
-   need to un-install those packages.
+   By default no package is installed.  Prior to August 2018, however,
+   if you downloaded a tarball, 3 packages (KSPACE, MANYBODY, MOLECULE)
+   were pre-installed via the traditional make procedure in the ``src``
+   directory.  That is no longer the case, so that CMake will build
+   as-is without needing to un-install those packages.
 
 ----------
 

doc/src/Build_settings.rst

@@ -6,7 +6,7 @@ explain how to do this for building both with CMake and make.
 
 * :ref:`C++11 standard compliance <cxx11>` when building all of LAMMPS
 * :ref:`FFT library <fft>` for use with the :doc:`kspace_style pppm <kspace_style>` command
-* :ref:`Size of LAMMPS data types <size>`
+* :ref:`Size of LAMMPS integer types <size>`
 * :ref:`Read or write compressed files <gzip>`
 * :ref:`Output of JPG and PNG files <graphics>` via the :doc:`dump image <dump_image>` command
 * :ref:`Output of movie files <graphics>` via the :doc:`dump_movie <dump_image>` command
@@ -44,74 +44,71 @@ require use of an FFT library to compute 1d FFTs.  The KISS FFT
 library is included with LAMMPS but other libraries can be faster.
 LAMMPS can use them if they are available on your system.
 
-CMake build
-^^^^^^^^^^^
+.. tabs::
 
-.. code-block:: bash
+   .. tab:: CMake build
 
-   -D FFT=value              # FFTW3 or MKL or KISS, default is FFTW3 if found, else KISS
-   -D FFT_SINGLE=value       # yes or no (default), no = double precision
-   -D FFT_PACK=value         # array (default) or pointer or memcpy
+      .. code-block:: bash
 
-.. note::
+         -D FFT=value              # FFTW3 or MKL or KISS, default is FFTW3 if found, else KISS
+         -D FFT_SINGLE=value       # yes or no (default), no = double precision
+         -D FFT_PACK=value         # array (default) or pointer or memcpy
 
-   The values for the FFT variable must be in upper-case.  This is
-   an exception to the rule that all CMake variables can be specified
-   with lower-case values.
+      .. note::
 
-Usually these settings are all that is needed.  If FFTW3 is selected,
-then CMake will try to detect, if threaded FFTW libraries are available
-and enable them by default.  This setting is independent of whether
-OpenMP threads are enabled and a packages like KOKKOS or USER-OMP is
-used.  If CMake cannot detect the FFT library, you can set these variables
-to assist:
+         The values for the FFT variable must be in upper-case.  This is
+         an exception to the rule that all CMake variables can be specified
+         with lower-case values.
 
-.. code-block:: bash
+      Usually these settings are all that is needed.  If FFTW3 is
+      selected, then CMake will try to detect, if threaded FFTW
+      libraries are available and enable them by default.  This setting
+      is independent of whether OpenMP threads are enabled and a
+      packages like KOKKOS or USER-OMP is used.  If CMake cannot detect
+      the FFT library, you can set these variables to assist:
 
-   -D FFTW3_INCLUDE_DIRS=path  # path to FFTW3 include files
-   -D FFTW3_LIBRARIES=path     # path to FFTW3 libraries
-   -D FFT_FFTW_THREADS=on      # enable using threaded FFTW3 libraries
-   -D MKL_INCLUDE_DIRS=path    # ditto for Intel MKL library
-   -D FFT_MKL_THREADS=on       # enable using threaded FFTs with MKL libraries
-   -D MKL_LIBRARIES=path
+      .. code-block:: bash
 
-Traditional make
-^^^^^^^^^^^^^^^^
+         -D FFTW3_INCLUDE_DIR=path   # path to FFTW3 include files
+         -D FFTW3_LIBRARY=path       # path to FFTW3 libraries
+         -D FFT_FFTW_THREADS=on      # enable using threaded FFTW3 libraries
+         -D MKL_INCLUDE_DIR=path     # ditto for Intel MKL library
+         -D FFT_MKL_THREADS=on       # enable using threaded FFTs with MKL libraries
+         -D MKL_LIBRARY=path         # path to MKL libraries
 
-To change the FFT library to be used and its options, you have to edit
-your machine Makefile. Below are examples how the makefile variables
-could be changed.
+   .. tab:: Traditional make
 
-.. code-block:: make
+      To change the FFT library to be used and its options, you have to edit
+      your machine Makefile. Below are examples how the makefile variables
+      could be changed.
 
-   FFT_INC = -DFFT_FFTW3         # -DFFT_FFTW3, -DFFT_FFTW (same as -DFFT_FFTW3), -DFFT_MKL, or -DFFT_KISS
-                                 # default is KISS if not specified
-   FFT_INC = -DFFT_SINGLE        # do not specify for double precision
-   FFT_INC = -DFFT_FFTW_THREADS  # enable using threaded FFTW3 libraries
-   FFT_INC = -DFFT_MKL_THREADS   # enable using threaded FFTs with MKL libraries
-   FFT_INC = -DFFT_PACK_ARRAY    # or -DFFT_PACK_POINTER or -DFFT_PACK_MEMCPY
+      .. code-block:: make
 
-# default is FFT_PACK_ARRAY if not specified
+         FFT_INC = -DFFT_FFTW3         # -DFFT_FFTW3, -DFFT_FFTW (same as -DFFT_FFTW3), -DFFT_MKL, or -DFFT_KISS
+                                       # default is KISS if not specified
+         FFT_INC = -DFFT_SINGLE        # do not specify for double precision
+         FFT_INC = -DFFT_FFTW_THREADS  # enable using threaded FFTW3 libraries
+         FFT_INC = -DFFT_MKL_THREADS   # enable using threaded FFTs with MKL libraries
+         FFT_INC = -DFFT_PACK_ARRAY    # or -DFFT_PACK_POINTER or -DFFT_PACK_MEMCPY
+                                       # default is FFT_PACK_ARRAY if not specified
 
-.. code-block:: make
+      .. code-block:: make
 
-   FFT_INC =       -I/usr/local/include
-   FFT_PATH =      -L/usr/local/lib
-   FFT_LIB =       -lfftw3             # FFTW3 double precision
-   FFT_LIB =       -lfftw3 -lfftw3_omp # FFTW3 double precision with threads (needs -DFFT_FFTW_THREADS)
-   FFT_LIB =       -lfftw3 -lfftw3f    # FFTW3 single precision
-   FFT_LIB =       -lmkl_intel_lp64 -lmkl_sequential -lmkl_core   # MKL with Intel compiler, serial interface
-   FFT_LIB =       -lmkl_gf_lp64 -lmkl_sequential -lmkl_core      # MKL with GNU compiler, serial interface
-   FFT_LIB =       -lmkl_intel_lp64 -lmkl_intel_thread -lmkl_core # MKL with Intel compiler, threaded interface
-   FFT_LIB =       -lmkl_gf_lp64 -lmkl_gnu_thread -lmkl_core      # MKL with GNU compiler, threaded interface
-   FFT_LIB =       -lmkl_rt            # MKL with automatic runtime selection of interface libs
+         FFT_INC =       -I/usr/local/include
+         FFT_PATH =      -L/usr/local/lib
+         FFT_LIB =       -lfftw3             # FFTW3 double precision
+         FFT_LIB =       -lfftw3 -lfftw3_omp # FFTW3 double precision with threads (needs -DFFT_FFTW_THREADS)
+         FFT_LIB =       -lfftw3 -lfftw3f    # FFTW3 single precision
+         FFT_LIB =       -lmkl_intel_lp64 -lmkl_sequential -lmkl_core   # MKL with Intel compiler, serial interface
+         FFT_LIB =       -lmkl_gf_lp64 -lmkl_sequential -lmkl_core      # MKL with GNU compiler, serial interface
+         FFT_LIB =       -lmkl_intel_lp64 -lmkl_intel_thread -lmkl_core # MKL with Intel compiler, threaded interface
+         FFT_LIB =       -lmkl_gf_lp64 -lmkl_gnu_thread -lmkl_core      # MKL with GNU compiler, threaded interface
+         FFT_LIB =       -lmkl_rt            # MKL with automatic runtime selection of interface libs
 
-As with CMake, you do not need to set paths in ``FFT_INC`` or ``FFT_PATH``, if
-the compiler can find the FFT header and library files in its default search path.
-You must specify ``FFT_LIB`` with the appropriate FFT libraries to include in the link.
-
-CMake build
-^^^^^^^^^^^
+      As with CMake, you do not need to set paths in ``FFT_INC`` or
+      ``FFT_PATH``, if the compiler can find the FFT header and library
+      files in its default search path.  You must specify ``FFT_LIB``
+      with the appropriate FFT libraries to include in the link.
 
 The `KISS FFT library <http://kissfft.sf.net>`_ is included in the LAMMPS
 distribution.  It is portable across all platforms.  Depending on the size
@@ -123,8 +120,9 @@ per-timestep CPU cost, FFTs are only a portion of long-range
 Coulombics, and 1d FFTs are only a portion of the FFT cost (parallel
 communication can be costly).  A breakdown of these timings is printed
 to the screen at the end of a run when using the
-:doc:`kspace_style pppm <kspace_style>` command. The :doc:`Run output <Run_output>`
-doc page gives more details.  A more detailed (and time consuming)
+:doc:`kspace_style pppm <kspace_style>` command. The
+:doc:`Screen and logfile output <Run_output>`
+page gives more details.  A more detailed (and time consuming)
 report of the FFT performance is generated with the
 :doc:`kspace_modify fftbench yes <kspace_modify>` command.
 
@@ -176,76 +174,103 @@ ARRAY mode.
 
 .. _size:
 
-Size of LAMMPS integer types
-------------------------------------
+Size of LAMMPS integer types and size limits
+--------------------------------------------
 
 LAMMPS has a few integer data types which can be defined as either
 4-byte (= 32-bit) or 8-byte (= 64-bit) integers at compile time.
+This has an impact on the size of a system that can be simulated
+or how large counters can become before "rolling over".
 The default setting of "smallbig" is almost always adequate.
 
-CMake build
-^^^^^^^^^^^
+.. tabs::
 
-.. code-block:: bash
+   .. tab:: CMake build
 
-   -D LAMMPS_SIZES=value   # smallbig (default) or bigbig or smallsmall
+      With CMake the choice of integer types is made via setting a
+      variable during configuration.
 
-Traditional build
-^^^^^^^^^^^^^^^^^
+      .. code-block:: bash
 
-If you want a setting different from the default, you need to edit your
-machine Makefile.
+         -D LAMMPS_SIZES=value   # smallbig (default) or bigbig or smallsmall
 
-.. code-block:: make
+      If the variable is not set explicitly, "smallbig" is used.
 
-   LMP_INC = -DLAMMPS_SMALLBIG    # or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL
+   .. tab:: Traditional build
 
-The default setting is ``-DLAMMPS_SMALLBIG`` if nothing is specified
+      If you want a setting different from the default, you need to edit the
+      ``LMP_INC`` variable setting your machine Makefile.
 
-CMake and make info
-^^^^^^^^^^^^^^^^^^^
+      .. code-block:: make
 
-The default "smallbig" setting allows for simulations with:
+         LMP_INC = -DLAMMPS_SMALLBIG    # or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL
 
-* total atom count = 2\^63 atoms (about 9e18)
-* total timesteps = 2\^63 (about 9e18)
-* atom IDs = 2\^31 (about 2 billion)
-* image flags = roll over at 512
+      The default setting is ``-DLAMMPS_SMALLBIG`` if nothing is specified
 
-The "bigbig" setting increases the latter two limits.  It allows for:
+LAMMPS system size restrictions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-* total atom count = 2\^63 atoms (about 9e18)
-* total timesteps = 2\^63 (about 9e18)
-* atom IDs = 2\^63 (about 9e18)
-* image flags = roll over at about 1 million (2\^20)
+.. list-table::
+   :header-rows: 1
+   :widths: auto
+   :align: center
 
-The "smallsmall" setting is only needed if your machine does not
-support 8-byte integers.  It allows for:
+   * -
+     - smallbig
+     - bigbig
+     - smallsmall
+   * - Total atom count
+     - :math:`2^{63}` atoms (= :math:`9.223 \cdot 10^{18}`)
+     - :math:`2^{63}` atoms (= :math:`9.223 \cdot 10^{18}`)
+     - :math:`2^{31}` atoms (= :math:`2.147 \cdot 10^9`)
+   * - Total timesteps
+     - :math:`2^{63}` steps (= :math:`9.223 \cdot 10^{18}`)
+     - :math:`2^{63}` steps (= :math:`9.223 \cdot 10^{18}`)
+     - :math:`2^{31}` steps (= :math:`2.147 \cdot 10^9`)
+   * - Atom ID values
+     - :math:`1 \le i \le 2^{31} (= 2.147 \cdot 10^9)`
+     - :math:`1 \le i \le 2^{63} (= 9.223 \cdot 10^{18})`
+     - :math:`1 \le i \le 2^{31} (= 2.147 \cdot 10^9)`
+   * - Image flag values
+     - :math:`-512 \le i \le 511`
+     - :math:`- 1\,048\,576 \le i \le 1\,048\,575`
+     - :math:`-512 \le i \le 511`
 
-* total atom count = 2\^31 atoms (about 2 billion)
-* total timesteps = 2\^31 (about 2 billion)
-* atom IDs = 2\^31 (about 2 billion)
-* image flags = roll over at 512 (2\^9)
+The "bigbig" setting increases the size of image flags and atom IDs over
+"smallbig" and the "smallsmall" setting is only needed if your machine
+does not support 64-bit integers or incurs performance penalties when
+using them.
+
+These are limits for the core of the LAMMPS code, specific features or
+some styles may impose additional limits.  The :ref:`USER-ATC
+<PKG-USER-ATC>` package cannot be compiled with the "bigbig" setting.
+Also, there are limitations when using the library interface where some
+functions with known issues have been replaced by dummy calls printing a
+corresponding error message rather than crashing randomly or corrupting
+data.
 
 Atom IDs are not required for atomic systems which do not store bond
 topology information, though IDs are enabled by default.  The
 :doc:`atom_modify id no <atom_modify>` command will turn them off.  Atom
 IDs are required for molecular systems with bond topology (bonds,
-angles, dihedrals, etc).  Thus if you model a molecular system with
-more than 2 billion atoms, you need the "bigbig" setting.
+angles, dihedrals, etc).  Similarly, some force or compute or fix styles
+require atom IDs.  Thus if you model a molecular system or use one of
+those styles with more than 2 billion atoms, you need the "bigbig"
+setting.
 
-Image flags store 3 values per atom which count the number of times an
-atom has moved through the periodic box in each dimension.  See the
-:doc:`dump <dump>` doc page for a discussion.  If an atom moves through
-the periodic box more than this limit, the value will "roll over",
-e.g. from 511 to -512, which can cause diagnostics like the
-mean-squared displacement, as calculated by the :doc:`compute msd <compute_msd>` command, to be faulty.
+Regardless of the total system size limits, the maximum number of atoms
+per MPI rank (local + ghost atoms) is limited to 2 billion for atomic
+systems and 500 million for systems with bonds (the additional
+restriction is due to using the 2 upper bits of the local atom index
+in neighbor lists for storing special bonds info).
 
-Note that the USER-ATC package and the USER-INTEL package are currently
-not compatible with the "bigbig" setting. Also, there are limitations
-when using the library interface. Some functions with known issues
-have been replaced by dummy calls printing a corresponding error rather
-than crashing randomly or corrupting data.
+Image flags store 3 values per atom in a single integer which count the
+number of times an atom has moved through the periodic box in each
+dimension.  See the :doc:`dump <dump>` manual page for a discussion.  If
+an atom moves through the periodic box more than this limit, the value
+will "roll over", e.g. from 511 to -512, which can cause diagnostics
+like the mean-squared displacement, as calculated by the :doc:`compute
+msd <compute_msd>` command, to be faulty.
 
 Also note that the GPU package requires its lib/gpu library to be
 compiled with the same size setting, or the link will fail.  A CMake
@@ -264,54 +289,51 @@ PNG image files.  Likewise the :doc:`dump movie <dump_image>` command
 outputs movie files in MPEG format.  Using these options requires the
 following settings:
 
-CMake build
-^^^^^^^^^^^
+.. tabs::
 
-.. code-block:: bash
+   .. tab:: CMake build
 
-   -D WITH_JPEG=value      # yes or no
-                           # default = yes if CMake finds JPEG files, else no
-   -D WITH_PNG=value       # yes or no
-                           # default = yes if CMake finds PNG and ZLIB files, else no
-   -D WITH_FFMPEG=value    # yes or no
-                           # default = yes if CMake can find ffmpeg, else no
+      .. code-block:: bash
 
-Usually these settings are all that is needed.  If CMake cannot find
-the graphics header, library, executable files, you can set these
-variables:
+         -D WITH_JPEG=value      # yes or no
+                                 # default = yes if CMake finds JPEG files, else no
+         -D WITH_PNG=value       # yes or no
+                                 # default = yes if CMake finds PNG and ZLIB files, else no
+         -D WITH_FFMPEG=value    # yes or no
+                                 # default = yes if CMake can find ffmpeg, else no
 
-.. code-block:: bash
+      Usually these settings are all that is needed.  If CMake cannot
+      find the graphics header, library, executable files, you can set
+      these variables:
 
-   -D JPEG_INCLUDE_DIR=path    # path to jpeglib.h header file
-   -D JPEG_LIBRARIES=path      # path to libjpeg.a (.so) file
-   -D PNG_INCLUDE_DIR=path     # path to png.h header file
-   -D PNG_LIBRARIES=path       # path to libpng.a (.so) file
-   -D ZLIB_INCLUDE_DIR=path    # path to zlib.h header file
-   -D ZLIB_LIBRARIES=path      # path to libz.a (.so) file
-   -D FFMPEG_EXECUTABLE=path   # path to ffmpeg executable
+      .. code-block:: bash
 
-Traditional make
-^^^^^^^^^^^^^^^^
+         -D JPEG_INCLUDE_DIR=path    # path to jpeglib.h header file
+         -D JPEG_LIBRARY=path        # path to libjpeg.a (.so) file
+         -D PNG_INCLUDE_DIR=path     # path to png.h header file
+         -D PNG_LIBRARY=path         # path to libpng.a (.so) file
+         -D ZLIB_INCLUDE_DIR=path    # path to zlib.h header file
+         -D ZLIB_LIBRARY=path        # path to libz.a (.so) file
+         -D FFMPEG_EXECUTABLE=path   # path to ffmpeg executable
 
-.. code-block:: make
+   .. tab:: Traditional make
 
-   LMP_INC = -DLAMMPS_JPEG
-   LMP_INC = -DLAMMPS_PNG
-   LMP_INC = -DLAMMPS_FFMPEG
+      .. code-block:: make
 
-   JPG_INC = -I/usr/local/include   # path to jpeglib.h, png.h, zlib.h header files if make cannot find them
-   JPG_PATH = -L/usr/lib            # paths to libjpeg.a, libpng.a, libz.a (.so) files if make cannot find them
-   JPG_LIB = -ljpeg -lpng -lz       # library names
+         LMP_INC = -DLAMMPS_JPEG
+         LMP_INC = -DLAMMPS_PNG
+         LMP_INC = -DLAMMPS_FFMPEG
 
-As with CMake, you do not need to set ``JPG_INC`` or ``JPG_PATH``,
-if make can find the graphics header and library files.  You must
-specify ``JPG_LIB``
-with a list of graphics libraries to include in the link.  You must
-insure ffmpeg is in a directory where LAMMPS can find it at runtime,
-that is a directory in your PATH environment variable.
+         JPG_INC = -I/usr/local/include   # path to jpeglib.h, png.h, zlib.h header files if make cannot find them
+         JPG_PATH = -L/usr/lib            # paths to libjpeg.a, libpng.a, libz.a (.so) files if make cannot find them
+         JPG_LIB = -ljpeg -lpng -lz       # library names
 
-CMake and make info
-^^^^^^^^^^^^^^^^^^^
+      As with CMake, you do not need to set ``JPG_INC`` or ``JPG_PATH``,
+      if make can find the graphics header and library files.  You must
+      specify ``JPG_LIB`` with a list of graphics libraries to include
+      in the link.  You must insure ffmpeg is in a directory where
+      LAMMPS can find it at runtime, that is a directory in your PATH
+      environment variable.
 
 Using ``ffmpeg`` to output movie files requires that your machine
 supports the "popen" function in the standard runtime library.
@@ -334,37 +356,34 @@ If this option is enabled, large files can be read or written with
 gzip compression by several LAMMPS commands, including
 :doc:`read_data <read_data>`, :doc:`rerun <rerun>`, and :doc:`dump <dump>`.
 
-CMake build
-^^^^^^^^^^^
+.. tabs::
 
-.. code-block:: bash
+   .. tab:: CMake build
 
-   -D WITH_GZIP=value       # yes or no
-                            # default is yes if CMake can find gzip, else no
-   -D GZIP_EXECUTABLE=path  # path to gzip executable if CMake cannot find it
+      .. code-block:: bash
 
-Traditional make
-^^^^^^^^^^^^^^^^
+         -D WITH_GZIP=value       # yes or no
+                                  # default is yes if CMake can find gzip, else no
+         -D GZIP_EXECUTABLE=path  # path to gzip executable if CMake cannot find it
 
-.. code-block:: make
+   .. tab:: Traditional make
 
-   LMP_INC = -DLAMMPS_GZIP
+      .. code-block:: make
 
-CMake and make info
-^^^^^^^^^^^^^^^^^^^
+         LMP_INC = -DLAMMPS_GZIP
 
-This option requires that your machine supports the "popen()" function
-in the standard runtime library and that a gzip executable can be
+This option requires that your operating system fully supports the "popen()"
+function in the standard runtime library and that a ``gzip`` executable can be
 found by LAMMPS during a run.
 
 .. note::
 
-   On some clusters with high-speed networks, using the fork()
-   library call (required by popen()) can interfere with the fast
-   communication library and lead to simulations using compressed output
-   or input to hang or crash. For selected operations, compressed file
-   I/O is also available using a compression library instead, which is
-   what the :ref:`COMPRESS package <PKG-COMPRESS>` enables.
+   On some clusters with high-speed networks, using the "fork()" library
+   call (required by "popen()") can interfere with the fast communication
+   library and lead to simulations using compressed output or input to
+   hang or crash. For selected operations, compressed file I/O is also
+   available using a compression library instead, which is what the
+   :ref:`COMPRESS package <PKG-COMPRESS>` enables.
 
 ----------
 
@@ -373,65 +392,66 @@ found by LAMMPS during a run.
 Memory allocation alignment
 ---------------------------------------
 
-This setting enables the use of the posix_memalign() call instead of
-malloc() when LAMMPS allocates large chunks or memory.  This can make
-vector instructions on CPUs more efficient, if dynamically allocated
-memory is aligned on larger-than-default byte boundaries.
-On most current systems, the malloc() implementation returns
+This setting enables the use of the "posix_memalign()" call instead of
+"malloc()" when LAMMPS allocates large chunks or memory.  Vector
+instructions on CPUs may become more efficient, if dynamically allocated
+memory is aligned on larger-than-default byte boundaries.  On most
+current operating systems, the "malloc()" implementation returns
 pointers that are aligned to 16-byte boundaries. Using SSE vector
-instructions efficiently, however, requires memory blocks being
-aligned on 64-byte boundaries.
+instructions efficiently, however, requires memory blocks being aligned
+on 64-byte boundaries.
 
-CMake build
-^^^^^^^^^^^
+.. tabs::
 
-.. code-block:: bash
+   .. tab:: CMake build
 
-   -D LAMMPS_MEMALIGN=value            # 0, 8, 16, 32, 64 (default)
+      .. code-block:: bash
 
-Use a ``LAMMPS_MEMALIGN`` value of 0 to disable using posix_memalign()
-and revert to using the malloc() C-library function instead.  When
-compiling LAMMPS for Windows systems, malloc() will always be used
-and this setting ignored.
+         -D LAMMPS_MEMALIGN=value            # 0, 8, 16, 32, 64 (default)
 
-Traditional make
-^^^^^^^^^^^^^^^^
+      Use a ``LAMMPS_MEMALIGN`` value of 0 to disable using
+      "posix_memalign()" and revert to using the "malloc()" C-library
+      function instead.  When compiling LAMMPS for Windows systems,
+      "malloc()" will always be used and this setting is ignored.
 
-.. code-block:: make
+   .. tab:: Traditional make
 
-   LMP_INC = -DLAMMPS_MEMALIGN=value   # 8, 16, 32, 64
+      .. code-block:: make
 
-Do not set ``-DLAMMPS_MEMALIGN``, if you want to have memory allocated
-with the malloc() function call instead. ``-DLAMMPS_MEMALIGN`` **cannot**
-be used on Windows, as it does use different function calls for
-allocating aligned memory, that are not compatible with how LAMMPS
-manages its dynamical memory.
+         LMP_INC = -DLAMMPS_MEMALIGN=value   # 8, 16, 32, 64
+
+      Do not set ``-DLAMMPS_MEMALIGN``, if you want to have memory
+      allocated with the "malloc()" function call
+      instead. ``-DLAMMPS_MEMALIGN`` **cannot** be used on Windows, as
+      Windows different function calls with different semantics for
+      allocating aligned memory, that are not compatible with how LAMMPS
+      manages its dynamical memory.
 
 ----------
 
 .. _longlong:
 
 Workaround for long long integers
-------------------------------------------------
+---------------------------------
 
 If your system or MPI version does not recognize "long long" data
 types, the following setting will be needed.  It converts "long long"
 to a "long" data type, which should be the desired 8-byte integer on
 those systems:
 
-CMake build
-^^^^^^^^^^^
+.. tabs::
 
-.. code-block:: bash
+   .. tab:: CMake build
 
-   -D LAMMPS_LONGLONG_TO_LONG=value     # yes or no (default)
+      .. code-block:: bash
 
-Traditional make
-^^^^^^^^^^^^^^^^
+         -D LAMMPS_LONGLONG_TO_LONG=value     # yes or no (default)
 
-.. code-block:: make
+   .. tab:: Traditional make
 
-   LMP_INC = -DLAMMPS_LONGLONG_TO_LONG
+      .. code-block:: make
+
+         LMP_INC = -DLAMMPS_LONGLONG_TO_LONG
 
 ----------
 
@@ -446,19 +466,19 @@ Instead, the call stack is unwound and control returns to the caller,
 e.g. to Python. Of course, the calling code has to be set up to
 *catch* exceptions thrown from within LAMMPS.
 
-CMake build
-^^^^^^^^^^^
+.. tabs::
 
-.. code-block:: bash
+   .. tab:: CMake build
 
-   -D LAMMPS_EXCEPTIONS=value        # yes or no (default)
+      .. code-block:: bash
 
-Traditional make
-^^^^^^^^^^^^^^^^
+         -D LAMMPS_EXCEPTIONS=value        # yes or no (default)
 
-.. code-block:: make
+   .. tab:: Traditional make
 
-   LMP_INC = -DLAMMPS_EXCEPTIONS
+      .. code-block:: make
+
+         LMP_INC = -DLAMMPS_EXCEPTIONS
 
 .. note::
 
@@ -466,3 +486,41 @@ Traditional make
    cleanly recover from an exception since not all parallel ranks may
    throw an exception and thus other MPI ranks may get stuck waiting for
    messages from the ones with errors.
+
+----------
+
+.. _trap_fpe:
+
+Trigger selected floating-point exceptions
+------------------------------------------
+
+Many kinds of CPUs have the capability to detect when a calculation
+results in an invalid math operation like a division by zero or calling
+the square root with a negative argument.  The default behavior on
+most operating systems is to continue and have values for ``NaN`` (= not
+a number) or ``Inf`` (= infinity).  This allows software to detect and
+recover from such conditions.  This behavior can be changed, however,
+often through use of compiler flags.  On Linux systems (or more general
+on systems using the GNU C library), these so-called floating-point traps
+can also be selectively enabled through library calls.  LAMMPS supports
+that by setting the ``-DLAMMPS_TRAP_FPE`` pre-processor define.  As it is
+done in the ``main()`` function, this applies only to the standalone
+executable, not the library.
+
+.. tabs::
+
+   .. tab:: CMake build
+
+      .. code-block:: bash
+
+         -D CMAKE_TUNE_FLAGS=-DLAMMPS_TRAP_FPE
+
+   .. tab:: Traditional make
+
+      .. code-block:: make
+
+         LMP_INC = -DLAMMPS_TRAP_FPE
+
+After compilation with this flag set, the LAMMPS executable will stop
+and produce a core dump when a division by zero, overflow, illegal math
+function argument or other invalid floating point operation is encountered.

doc/src/Build_windows.rst

@@ -38,7 +38,7 @@ optional Windows feature allows you to run the bash shell from Ubuntu
 from within Windows and from there on, you can pretty much use that
 shell like you are running on an Ubuntu Linux machine (e.g. installing
 software via apt-get and more). For more details on that, please
-see :doc:`this tutorial <Howto_wsl>`
+see :doc:`this tutorial <Howto_wsl>`.
 
 .. _gnu:
 

doc/src/Classes.rst

@@ -0,0 +1,38 @@
+LAMMPS C++ base classes
+=======================
+
+LAMMPS is designed to be used as a C++ class library where one can set
+up and drive a simulation through creating a class instance and then
+calling some abstract operations or commands on that class or its member
+class instances.  These are interfaced to the :doc:`C library API
+<Library>`, which providing an additional level of abstraction
+simplification for common operations. The C API is also the basis for
+calling LAMMPS from Python or Fortran.
+
+When used from a C++ program, most of the symbols and functions in
+LAMMPS are wrapped into the ``LAMMPS_NS`` namespace so they will not
+collide with your own classes or other libraries. This, however, does
+not extend to the additional libraries bundled with LAMMPS in the lib
+folder and some of the low-level code of some packages.
+
+Behind the scenes this is implemented through inheritance and
+polymorphism where base classes define the abstract interface and
+derived classes provide the specialized implementation for specific
+models or optimizations or ports to accelerator platforms.  This
+document will provide an outline of the fundamental class hierarchy and
+some selected examples for derived classes of specific models.
+
+.. note::
+
+   Please see the :ref:`note about thread-safety <thread-safety>`
+   in the library Howto doc page.
+
+-----------------------------------
+
+.. toctree::
+   :caption: Individual Base Classes
+   :name: lammpsbase
+
+   Classes_lammps
+   Classes_atom
+   Classes_input

doc/src/Classes_atom.rst

@@ -0,0 +1,9 @@
+LAMMPS Atom and AtomVec Base Classes
+************************************
+
+.. doxygenclass:: LAMMPS_NS::Atom
+   :project: progguide
+   :members:
+
+
+

doc/src/Classes_input.rst

@@ -0,0 +1,7 @@
+LAMMPS Input Base Class
+************************
+
+.. doxygenclass:: LAMMPS_NS::Input
+      :project: progguide
+      :members:
+

doc/src/Classes_lammps.rst

@@ -0,0 +1,33 @@
+LAMMPS Class
+************
+
+The LAMMPS class is encapsulating an MD simulation state and thus it is
+the class that needs to be created when starting a new simulation system
+state.  The LAMMPS executable essentially creates one instance of this
+class and passes the command line flags and tells it to process the
+provided input (a file or ``stdin``).  It shuts the class down when
+control is returned to it and then exits.  When using LAMMPS as a
+library from another code it is required to create an instance of this
+class, either directly from C++ with ``new LAMMPS()`` or through one
+of the library interface functions like :cpp:func:`lammps_open` of the
+C-library interface, or the :py:class:`lammps.lammps` class constructor
+of the Python module, or the :f:func:`lammps` constructor of the Fortran
+module.
+
+In order to avoid clashes of function names, all of the core code in
+LAMMPS is placed into the ``LAMMPS_NS`` namespace.  Functions or variables
+outside of that namespace must be "static", i.e.  visible only to the
+scope of the file/object they are defined in.  Code in packages or the
+libraries in the ``lib`` folder may not adhere to this as some of them
+are adapted from legacy code or consist of external libraries with their
+own requirements and policies.
+
+--------------------
+
+.. doxygenclass:: LAMMPS_NS::LAMMPS
+   :project: progguide
+   :members:
+
+.. doxygenclass:: LAMMPS_NS::Pointers
+   :project: progguide
+

doc/src/Commands_fix.rst

@@ -150,6 +150,7 @@ OPT.
    * :doc:`orient/bcc <fix_orient>`
    * :doc:`orient/fcc <fix_orient>`
    * :doc:`orient/eco <fix_orient_eco>`
+   * :doc:`pafi <fix_pafi>`
    * :doc:`phonon <fix_phonon>`
    * :doc:`pimd <fix_pimd>`
    * :doc:`planeforce <fix_planeforce>`

doc/src/Commands_pair.rst

@@ -81,6 +81,7 @@ OPT.
    * :doc:`coul/slater/long <pair_coul_slater>`
    * :doc:`coul/shield <pair_coul_shield>`
    * :doc:`coul/streitz <pair_coul>`
+   * :doc:`coul/tt <pair_coul_tt>`
    * :doc:`coul/wolf (ko) <pair_coul>`
    * :doc:`coul/wolf/cs <pair_cs>`
    * :doc:`dpd (gio) <pair_dpd>`

doc/src/Commands_removed.rst

@@ -17,6 +17,11 @@ ways through the :doc:`compute chunk/atom <compute_chunk_atom>` command
 and then averaging is done using :doc:`fix ave/chunk <fix_ave_chunk>`.
 Please refer to the :doc:`chunk HOWTO <Howto_chunk>` section for an overview.
 
+Reset_ids command
+-----------------
+
+The reset_ids command has been renamed to :doc:`reset_atom_ids <reset_atom_ids>`.
+
 MEAM package
 ------------
 
@@ -27,7 +32,7 @@ which removes several restrictions (e.g. there can be multiple instances
 in hybrid pair styles) and allows for some optimizations leading
 to better performance.  The new pair style :doc:`meam/c <pair_meamc>` has
 the exact same syntax as the old "meam" pair style and thus pair style
-:doc:`meam <pair_meamc>` is an alias to the new style and backward
+meam is an alias to the new style and backward
 compatibility of old inputs is preserved.
 
 REAX package

doc/src/Cplusplus.rst

@@ -0,0 +1,90 @@
+Using the C++ API directly
+**************************
+
+Using the C++ classes of the LAMMPS library is lacking some of the
+convenience of the C library API, but it allows a more direct access to
+simulation data and thus more low-level manipulations and tighter
+integration of LAMMPS into another code.  While for the complete C
+library API is provided in the ``library.h`` header file, for using
+the C++ API it is required to include the individual header files
+defining the individual classes in use.  Typically the name of the
+class and the name of the header follow some simple rule.  Examples
+are given below.
+
+
+Creating or deleting a LAMMPS object
+*************************************
+
+When using the LAMMPS library interfaces, the core task is to create an
+instance of the :cpp:class:`LAMMPS_NS::LAMMPS` class.  In C++ this can
+be done directly through the ``new`` operator.  All further operations
+are then initiated through calling member functions of some of the
+components of the LAMMPS class or accessing their data members.  The
+destruction of the LAMMPS instance is correspondingly initiated by using
+the ``delete`` operator.  Here is a simple example:
+
+.. code-block:: c++
+
+   #include "lammps.h"
+
+   #include <mpi.h>
+   #include <iostream>
+
+   int main(int argc, char **argv)
+   {
+       LAMMPS_NS::LAMMPS *lmp;
+       // custom argument vector for LAMMPS library
+       const char *lmpargv[] {"liblammps", "-log", "none"};
+       int lmpargc = sizeof(lmpargv)/sizeof(const char *);
+
+       // explicitly initialize MPI
+       MPI_Init(&argc, &argv);
+
+       // create LAMMPS instance
+       lmp = new LAMMPS_NS::LAMMPS(lmpargc, (char **)lmpargv, MPI_COMM_WORLD);
+       // output numerical version string
+       std::cout << "LAMMPS version ID: " << lmp->num_ver << std::endl;
+       // delete LAMMPS instance
+       delete lmp;
+
+       // stop MPI environment
+       MPI_Finalize();
+       return 0;
+   }
+
+This minimal example only requires to include the ``lammps.h`` header
+file since it only accesses a non-pointer member of the LAMMPS class.
+
+
+Executing LAMMPS commands
+*************************
+
+Once a LAMMPS instance is created by your C++ code, you need to set up a
+simulation and that is most conveniently done by "driving" it through
+issuing commands like you would do when running a LAMMPS simulation from
+an input script. Processing of input in LAMMPS is handled by the
+:cpp:class:`Input <LAMMPS_NS::Input>` class an instance of which is a
+member of the :cpp:class:`LAMMPS <LAMMPS_NS::LAMMPS>` class.  You have
+two options: reading commands from a file, or executing a single
+command from a string. See below for a small example:
+
+.. code-block:: c++
+
+   #include "lammps.h"
+   #include "input.h"
+   #include <mpi.h>
+
+   using namespace LAMMPS_NS;
+
+   int main(int argc, char **argv)
+   {
+       const char *lmpargv[] {"liblammps", "-log", "none"};
+       int lmpargc = sizeof(lmpargv)/sizeof(const char *);
+
+       MPI_Init(&argc, &argv);
+       LAMMPS *lmp = new LAMMPS(lmpargc, (char **)lmpargv, MPI_COMM_WORLD);
+       lmp->input->file("in.melt");
+       lmp->input->one("run 100 post no");
+       delete lmp;
+       return 0;
+   }

doc/src/Developer.rst

@@ -0,0 +1,17 @@
+LAMMPS Developer Guide
+**********************
+
+This section describes the internal structure and basic algorithms
+of the LAMMPS code. This is a work in progress and additional
+information will be added incrementally depending on availability
+of time and requests from the LAMMPS user community.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   Developer_org
+   Developer_flow
+   Developer_write
+   Developer_utils
+   Classes

doc/src/Developer/.gitignore

@@ -1,3 +0,0 @@
-/developer.aux
-/developer.log
-/developer.toc

doc/src/Developer/classes.fig

@@ -1,198 +0,0 @@
-#FIG 3.2  Produced by xfig version 3.2.5a
-Portrait
-Center
-Inches
-Letter  
-100.00
-Single
--2
-1200 2
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 2232 1170 3540 1170 3540 1505 2232 1505 2232 1170
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 2220 1830 3015 1830 3015 2219 2220 2219 2220 1830
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 2226 3285 3300 3285 3300 3665 2226 3665 2226 3285
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 2223 5190 3225 5190 3225 5525 2223 5525 2223 5190
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 2232 7125 3090 7125 3090 7478 2232 7478 2232 7125
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 2226 10230 3300 10230 3300 10565 2226 10565 2226 10230
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 4026 10305 4980 10305 4980 10592 4026 10592 4026 10305
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 4029 9900 5205 9900 5205 10250 4029 10250 4029 9900
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 4038 9315 5370 9315 5370 9659 4038 9659 4038 9315
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 4023 8955 4530 8955 4530 9278 4023 9278 4023 8955
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 4029 8475 5190 8475 5190 8762 4029 8762 4029 8475
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 4008 8115 5430 8115 5430 8408 4008 8408 4008 8115
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 4026 7425 4995 7425 4995 7712 4026 7712 4026 7425
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 4035 6720 4650 6720 4650 7025 4035 7025 4035 6720
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 4044 7080 4830 7080 4830 7358 4044 7358 4044 7080
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 4032 6105 5205 6105 5205 6419 4032 6419 4032 6105
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 4026 5715 5115 5715 5115 6062 4026 6062 4026 5715
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 4023 3585 4605 3585 4605 3872 4023 3872 4023 3585
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 3954 1680 5175 1680 5175 1997 3954 1997 3954 1680
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
-	1 1 2.00 120.00 240.00
-	 1620 5235 2100 615
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
-	1 1 2.00 120.00 240.00
-	 1605 5445 2070 10695
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
-	1 1 2.00 120.00 240.00
-	 3120 1935 3855 1800
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
-	1 1 2.00 120.00 240.00
-	 3150 2115 3765 2250
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
-	1 1 2.00 120.00 240.00
-	 3135 7230 3945 6840
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
-	1 1 2.00 120.00 240.00
-	 3150 7335 3945 8610
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
-	1 1 2.00 120.00 240.00
-	 5265 8610 6195 8400
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
-	1 1 2.00 120.00 240.00
-	 5280 8655 6180 8820
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
-	1 1 2.00 120.00 240.00
-	 3345 10290 3930 10020
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
-	1 1 2.00 120.00 240.00
-	 3360 10395 3930 10425
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
-	1 1 2.00 120.00 240.00
-	 3360 10455 3930 10755
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 2193 360 3435 360 3435 647 2193 647 2193 360
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
-	1 1 2.00 120.00 240.00
-	 3398 3472 3923 3307
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
-	1 1 2.00 120.00 240.00
-	 3413 3601 3923 3721
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
-	1 1 2.00 120.00 240.00
-	 3285 2806 3870 2802
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
-	1 1 2.00 120.00 240.00
-	 3315 5372 3900 5368
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 6354 2280 7470 2280 7470 2585 6354 2585 6354 2280
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 6348 1875 7320 1875 7320 2222 6348 2222 6348 1875
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 3954 2070 5505 2070 5505 2372 3954 2372 3954 2070
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
-	1 1 2.00 120.00 240.00
-	 5634 2137 6230 2045
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
-	1 1 2.00 120.00 240.00
-	 5670 2310 6265 2418
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 3900 2640 5400 2640 5400 2975 3900 2975 3900 2640
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 4038 3165 5385 3165 5385 3497 4038 3497 4038 3165
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 4245 4110 5730 4110 5730 4499 4245 4499 4245 4110
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 4233 4545 6390 4545 6390 4862 4233 4862 4233 4545
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 4026 5190 5385 5190 5385 5525 4026 5525 4026 5190
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 4038 7755 5310 7755 5310 8075 4038 8075 4038 7755
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 6270 8250 7365 8250 7365 8610 6270 8610 6270 8250
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 6273 8655 7380 8655 7380 8978 6273 8978 6273 8655
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 4041 10620 5985 10620 5985 10943 4041 10943 4041 10620
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 2217 10830 3135 10830 3135 11156 2217 11156 2217 10830
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 2229 9780 3240 9780 3240 10118 2229 10118 2229 9780
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 2214 9015 3285 9015 3285 9362 2214 9362 2214 9015
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 2208 5850 3420 5850 3420 6209 2208 6209 2208 5850
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 2217 4275 3615 4275 3615 4634 2217 4634 2217 4275
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 2235 2655 3150 2655 3150 3000 2235 3000 2235 2655
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 60 5115 1500 5115 1500 5610 60 5610 60 5115
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
-	1 1 2.00 120.00 240.00
-	 3486 6018 4011 5853
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
-	1 1 2.00 120.00 240.00
-	 3486 6129 3996 6249
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
-	1 1 2.00 120.00 240.00
-	 3361 9291 3991 9531
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
-	1 1 2.00 120.00 240.00
-	 3345 9129 4005 9099
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
-	1 1 2.00 120.00 240.00
-	 3691 4412 4216 4277
-2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
-	1 1 2.00 120.00 240.00
-	 3695 4561 4175 4711
-2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
-	 2220 735 3129 735 3129 1043 2220 1043 2220 735
-4 0 1 50 -1 18 18 0.0000 4 225 1275 2265 1455 Universe\001
-4 0 1 50 -1 18 18 0.0000 4 285 735 2265 2175 Input\001
-4 0 1 50 -1 18 18 0.0000 4 225 780 2265 2925 Atom\001
-4 0 1 50 -1 18 18 0.0000 4 285 1020 2265 3600 Update\001
-4 0 1 50 -1 18 18 0.0000 4 285 1320 2265 4575 Neighbor\001
-4 0 1 50 -1 18 18 0.0000 4 225 945 2265 5475 Comm\001
-4 0 1 50 -1 18 18 0.0000 4 225 1110 2265 6150 Domain\001
-4 0 1 50 -1 18 18 0.0000 4 225 810 2265 7425 Force\001
-4 0 1 50 -1 18 18 0.0000 4 285 975 2265 9300 Modify\001
-4 0 1 50 -1 18 18 0.0000 4 285 900 2265 10050 Group\001
-4 0 1 50 -1 18 18 0.0000 4 285 990 2265 10500 Output\001
-4 0 1 50 -1 18 18 0.0000 4 225 825 2265 11100 Timer\001
-4 0 0 50 -1 18 18 0.0000 4 225 1170 3990 1950 Variable\001
-4 0 4 50 -1 18 18 0.0000 4 225 1470 3990 2325 Command\001
-4 0 4 50 -1 18 18 0.0000 4 285 1275 4065 3450 Integrate\001
-4 0 4 50 -1 18 18 0.0000 4 225 525 4065 3825 Min\001
-4 0 0 50 -1 18 18 0.0000 4 285 1230 4065 5475 Irregular\001
-4 0 4 50 -1 18 18 0.0000 4 285 1020 4065 6000 Region\001
-4 0 0 50 -1 18 18 0.0000 4 225 975 4065 6375 Lattice\001
-4 0 4 50 -1 18 18 0.0000 4 225 435 4065 9225 Fix\001
-4 0 4 50 -1 18 18 0.0000 4 285 1305 4065 9600 Compute\001
-4 0 4 50 -1 18 18 0.0000 4 225 570 4065 6975 Pair\001
-4 0 4 50 -1 18 18 0.0000 4 285 840 4065 7665 Angle\001
-4 0 4 50 -1 18 18 0.0000 4 225 1215 4065 8010 Dihedral\001
-4 0 4 50 -1 18 18 0.0000 4 285 1305 4065 8355 Improper\001
-4 0 4 50 -1 18 18 0.0000 4 285 1095 4065 8700 KSpace\001
-4 0 4 50 -1 18 18 0.0000 4 285 855 4065 10545 Dump\001
-4 0 0 50 -1 18 18 0.0000 4 225 1815 4065 10890 WriteRestart\001
-4 0 0 50 -1 18 18 0.0000 4 225 930 6315 8550 FFT3D\001
-4 0 0 50 -1 18 18 0.0000 4 285 1005 6315 8925 Remap\001
-4 0 0 50 -1 18 18 0.0000 4 225 885 6390 2175 Finish\001
-4 0 0 50 -1 18 18 0.0000 4 285 1050 6390 2550 Special\001
-4 0 4 50 -1 18 18 0.0000 4 225 1305 3990 2925 AtomVec\001
-4 0 4 50 -1 18 18 0.0000 4 225 765 4065 7320 Bond\001
-4 0 0 50 -1 18 18 0.0000 4 225 1095 4065 10200 Thermo\001
-4 0 0 50 -1 18 18 0.0000 4 285 1380 4305 4425 NeighList\001
-4 0 0 50 -1 18 18 0.0000 4 285 2025 4305 4800 NeighRequest\001
-4 0 1 50 -1 18 18 0.0000 4 285 1155 2250 600 Memory\001
-4 0 0 50 -1 18 18 0.0000 4 225 1305 120 5475 LAMMPS\001
-4 0 1 50 -1 18 18 0.0000 4 225 735 2265 1005 Error\001

doc/src/Developer/developer.tex

@@ -1,699 +0,0 @@
-\documentclass{article}
-\usepackage{graphicx}
-
-\begin{document}
-
-\centerline{\Large \bf LAMMPS Developer Guide}
-\centerline{\bf 23 Aug 2011}
-
-\vspace{0.5in}
-
-This document is a developer guide to the LAMMPS molecular dynamics
-package, whose WWW site is at lammps.sandia.gov.  It describes the
-internal structure and algorithms of the code.  Sections will be added
-as we have time, and in response to requests from developers and
-users.
-
-\tableofcontents
-
-\pagebreak
-\section{LAMMPS source files}
-
-LAMMPS source files are in two directories of the distribution
-tarball.  The src directory has the majority of them, all of which are
-C++ files (*.cpp and *.h).  Many of these files are in the src
-directory itself.  There are also dozens of ``packages'', which can be
-included or excluded when LAMMPS is built.  See the
-doc/Section\_build.html section of the manual for more information
-about packages, or type ``make'' from within the src directory, which
-lists package-related commands, such as ``make package-status''.  The
-source files for each package are in an all-uppercase sub-directory of
-src, like src/MOLECULE or src/USER-CUDA.  If the package is currently
-installed, copies of the package source files will also exist in the
-src directory itself.  The src/STUBS sub-directory is not a package
-but contains a dummy version of the MPI library, used when building a
-serial version of the code.
-
-The lib directory also contains source code for external libraries,
-used by a few of the packages.  Each sub-directory, like meam or gpu,
-contains the source files, some of which are in different languages
-such as Fortran.  The files are compiled into libraries from within
-each sub-directory, e.g. performing a ``make'' in the lib/meam directory
-creates a libmeam.a file.  These libraries are linked to during a
-LAMMPS build, if the corresponding package is installed.
-
-LAMMPS C++ source files almost always come in pairs, such as run.cpp
-and run.h.  The pair of files defines a C++ class, the Run class in
-this case, which contains the code invoked by the ``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. ``force.cpp'' and the Force
-class.  They are discussed in the next section.
-
-\pagebreak
-\section{Class hierarchy of LAMMPS}
-
-Though LAMMPS has a lot of source files and classes, its class
-hierarchy is quite simple, as outlined in Fig \ref{fig:classes}.  Each
-boxed name refers to a class and has a pair of associated source files
-in lammps/src, e.g. ``memory.cpp'' and ``memory.h''.  More details on the
-class and its methods and data structures can be found by examining
-its *.h file.
-
-LAMMPS (lammps.cpp/h) is the top-level class for the entire code.  It
-holds an ``instance'' of LAMMPS and can be instantiated one or more
-times by a calling code.  For example, the file src/main.cpp simply
-instantiates one instance of LAMMPS and passes it the input script.
-
-The file src/library.cpp contains a C-style library interface to the
-LAMMPS class.  See the lammps/couple and lammps/python directories for
-examples of simple programs that use LAMMPS through its library
-interface.  A driver program can instantiate the LAMMPS class multiple
-times, e.g. to embed several atomistic simulation regions within a
-mesoscale or continuum simulation domain.
-
-There are a dozen or so top-level classes within the LAMMPS class that
-are visible everywhere in the code.  They are shaded blue in Fig
-\ref{fig:classes}.  Thus any class can refer to the y-coordinate of
-local atom $I$ as atom$\rightarrow$x[i][1].  This visibility is
-enabled by a bit of cleverness in the Pointers class (see
-src/pointers.h) which every class inherits from.
-
-There are a handful of virtual parent classes in LAMMPS that define
-what LAMMPS calls ``styles''.  They are shaded red in Fig
-\ref{fig:classes}.  Each of these are parents of a number of child
-classes that implement the interface defined by the parent class.  For
-example, the fix style has around 100 child classes.  They are the
-possible fixes that can be specified by the fix command in an input
-script, e.g. fix nve, fix shake, fix ave/time, etc.  The corresponding
-classes are Fix (for the parent class), FixNVE, FixShake, FixAveTime,
-etc.  The source files for these classes are easy to identify in the
-src directory, since they begin with the word ``fix'', e,g,
-fix\_nve.cpp, fix\_shake,cpp, fix\_ave\_time.cpp, etc.
-
-The one exception is child class files for the ``command'' style.  These
-implement specific commands in the input script that can be invoked
-before/after/between runs or which launch a simulation.  Examples are
-the create\_box, minimize, run, and velocity commands which encode the
-CreateBox, Minimize, Run, and Velocity classes.  The corresponding
-files are create\_box,cpp, minimize.cpp, run.cpp, and velocity.cpp.
-The list of command style files can be found by typing ``grep
-COMMAND\_CLASS *.h'' from within the src directory, since that word in
-the header file identifies the class as an input script command.
-Similar words can be grepped to list files for the other LAMMPS
-styles.  E.g. ATOM\_CLASS, PAIR\_CLASS, BOND\_CLASS, REGION\_CLASS,
-FIX\_CLASS, COMPUTE\_CLASS, DUMP\_CLASS, etc.
-
-\begin{figure}[htb]
- \begin{center}
- \includegraphics[height=4in]{classes.pdf}
- \end{center}
- \caption{Class hierarchy within LAMMPS source code.}
-\label{fig:classes}
-\end{figure}
-
-More details on individual classes in Fig \ref{fig:classes} are as
-follows:
-
-\begin{itemize}
-
-\item The Memory class handles allocation of all large vectors and
-  arrays.
-
-\item The Error class prints all error and warning messages.
-
-\item 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.
-
-\item The Input class reads an input script, stores variables, and
-  invokes stand-alone commands that are child classes of the Command
-  class.
-
-\item As discussed above, the Command class is a parent class for
-  certain input script commands that perform a one-time operation
-  before/after/between simulations or which invoke a simulation.  They
-  are instantiated from within the Input class, invoked, then
-  immediately destructed.
-
-\item The Finish class is instantiated to print statistics to the
-  screen after a simulation is performed, by commands like run and
-  minimize.
-
-\item The Special class walks the bond topology of a molecular system
-  to find first, second, third neighbors of each atom.  It is invoked by
-  several commands, like read\_data, read\_restart, and replicate.
-
-\item The Atom class stores all per-atom arrays.  More precisely, they
-  are allocated and stored by the AtomVec class, and the Atom class
-  simply stores a pointer to them.  The AtomVec class is a parent
-  class for atom styles, defined by the atom\_style command.
-
-\item The Update class holds an integrator and a minimizer.  The
-  Integrate class is a parent style for the Verlet and rRESPA time
-  integrators, as defined by the run\_style input command.  The Min
-  class is a parent style for various energy minimizers.
-
-\item The Neighbor class builds and stores neighbor lists.  The
-  NeighList class stores a single list (for all atoms).  The
-  NeighRequest class is called by pair, fix, or compute styles when
-  they need a particular kind of neighbor list.
-
-\item The Comm class performs interprocessor communication, typically
-  of ghost atom information.  This usually involves MPI message
-  exchanges with 6 neighboring processors in the 3d logical grid of
-  processors mapped to the simulation box.  Sometimes the Irregular
-  class is used, when atoms may migrate to arbitrary processors.
-
-\item The Domain class stores the simulation box geometry, as well as
-  geometric Regions and any user definition of a Lattice.  The latter
-  are defined by region and lattice commands in an input script.
-
-\item The Force class computes various forces between atoms.  The Pair
-  parent class is for non-bonded or pair-wise forces, which in LAMMPS
-  lingo includes many-body forces such as the Tersoff 3-body
-  potential.  The Bond, Angle, Dihedral, Improper parent classes are
-  styles for bonded interactions within a static molecular topology.
-  The KSpace parent class is for computing long-range Coulombic
-  interactions.  One of its child classes, PPPM, uses the FFT3D and
-  Remap classes to communicate grid-based information with neighboring
-  processors.
-
-\item The Modify class stores lists of Fix and Compute classes, both
-  of which are parent styles.
-
-\item The Group class manipulates groups that atoms are assigned to
-  via the group command.  It also computes various attributes of
-  groups of atoms.
-
-\item The Output class is used to generate 3 kinds of output from a
-  LAMMPS simulation: thermodynamic information printed to the screen
-  and log file, dump file snapshots, and restart files.  These
-  correspond to the Thermo, Dump, and WriteRestart classes
-  respectively.  The Dump class is a parent style.
-
-\item The Timer class logs MPI timing information, output at the end
-  of a run.
-
-\end{itemize}
-
-%%\pagebreak
-%%\section{Spatial decomposition and parallel operations}
-%%distributed memory
-%%Ref to JCP paper
-%%diagram of 3d grid of procs and spatial decomp
-%%6-way comm
-%%ghost atoms, PBC added when comm (in atom class)
-
-%%\pagebreak
-%%\section{Fixes, computes, variables}
-%%fixes intercolate in timestep, store per-atom info
-%%computes based on current snapshot
-%%equal- and atom-style variables
-%%output they produce - see write-up in HowTo
-
-\pagebreak
-\section{How a timestep works}
-
-The first and most fundamental operation within LAMMPS to understand
-is how a timestep is structured.  Timestepping is performed by the
-Integrate class within the Update class.  Since Integrate is a parent
-class, corresponding to the run\_style input script command, it has
-child classes.  In this section, the timestep implemented by the
-Verlet child class is described.  A similar timestep is implemented by
-the Respa child class, for the rRESPA hierarchical timestepping
-method.  The Min parent class performs energy minimization, so does
-not perform a literal timestep.  But it has logic similar to what is
-described here, to compute forces and invoke fixes at each iteration
-of a minimization.  Differences between time integration and
-minimization are highlighted at the end of this section.
-
-The Verlet class is encoded in the src/verlet.cpp and verlet.h files.
-It implements the velocity-Verlet timestepping algorithm.  The
-workhorse method is Verlet::run(), but first we highlight several
-other methods in the class.
-
-\begin{itemize}
-
-\item The init() method is called at the beginning of each dynamics
-  run.  It simply sets some internal flags, based on user settings in
-  other parts of the code.
-
-\item The setup() or setup\_minimal() methods are also called before
-  each run.  The velocity-Verlet method requires current forces be
-  calculated before the first timestep, so these routines compute
-  forces due to all atomic interactions, using the same logic that
-  appears in the timestepping described next.  A few fixes are also
-  invoked, using the mechanism described in the next section.  Various
-  counters are also initialized before the run begins.  The
-  setup\_minimal() method is a variant that has a flag for performing
-  less setup.  This is used when runs are continued and information
-  from the previous run is still valid.  For example, if repeated
-  short LAMMPS runs are being invoked, interleaved by other commands,
-  via the ``pre no'' and ``every'' options of the run command, the
-  setup\_minimal() method is used.
-
-\item The force\_clear() method initializes force and other arrays to
-  zero before each timestep, so that forces (torques, etc) can be
-  accumulated.
-
-\end{itemize}
-
-Now for the Verlet::run() method.  Its structure in hi-level pseudo
-code is shown in Fig \ref{fig:verlet}.  In the actual code in
-src/verlet.cpp some of these operations are conditionally invoked.
-
-\begin{figure}[htb]
- \begin{center}
- \begin{verbatim}
-loop over N timesteps:
-  ev_set()
-
-  fix->initial_integrate()
-  fix->post_integrate()
-
-  nflag = neighbor->decide()
-  if nflag:
-    fix->pre_exchange()
-    domain->pbc()
-    domain->reset_box()
-    comm->setup()
-    neighbor->setup_bins()
-    comm->exchange()
-    comm->borders()
-    fix->pre_neighbor()
-    neighbor->build()
-  else
-    comm->forward_comm()
-
-  force_clear()
-  fix->pre_force()
-
-  pair->compute()
-  bond->compute()
-  angle->compute()
-  dihedral->compute()
-  improper->compute()
-  kspace->compute()
-
-  comm->reverse_comm()
-
-  fix->post_force()
-  fix->final_integrate()
-  fix->end_of_step()
-
-  if any output on this step: output->write()
-  \end{verbatim}
- \end{center}
- \caption{Pseudo-code for the Verlet::run() method.}
-\label{fig:verlet}
-\end{figure}
-
-The ev\_set() method (in the parent Integrate class), sets two flags
-({\em eflag} and {\em vflag}) for energy and virial computation.  Each
-flag encodes whether global and/or per-atom energy and virial should
-be calculated on this timestep, because some fix or variable or output
-will need it.  These flags are passed to the various methods that
-compute particle interactions, so that they can skip the extra
-calculations if the energy and virial are not needed.  See the
-comments with the Integrate::ev\_set() method which document the flag
-values.
-
-At various points of the timestep, fixes are invoked,
-e.g. fix$\rightarrow$initial\_integrate().  In the code, this is
-actually done via the Modify class which stores all the Fix objects
-and lists of which should be invoked at what point in the timestep.
-Fixes are the LAMMPS mechanism for tailoring the operations of a
-timestep for a particular simulation.  As described elsewhere
-(unwritten section), each fix has one or more methods, each of which
-is invoked at a specific stage of the timestep, as in Fig
-\ref{fig:verlet}.  All the fixes defined in an input script with an
-initial\_integrate() method are invoked at the beginning of each
-timestep.  Fix nve, nvt, npt are examples, since they perform the
-start-of-timestep velocity-Verlet integration to update velocities by
-a half-step, and coordinates by a full step.  The post\_integrate()
-method is next.  Only a few fixes use this, e.g. to reflect particles
-off box boundaries in the FixWallReflect class.
-
-The decide() method in the Neighbor class determines whether neighbor
-lists need to be rebuilt on the current timestep.  If not, coordinates
-of ghost atoms are acquired by each processor via the forward\_comm()
-method of the Comm class.  If neighbor lists need to be built, several
-operations within the inner if clause of Fig \ref{fig:verlet} are
-first invoked.  The pre\_exchange() method of any defined fixes is
-invoked first.  Typically this inserts or deletes particles from the
-system.
-
-Periodic boundary conditions are then applied by the Domain class via
-its pbc() method to remap particles that have moved outside the
-simulation box back into the box.  Note that this is not done every
-timestep. but only when neighbor lists are rebuilt.  This is so that
-each processor's sub-domain will have consistent (nearby) atom
-coordinates for its owned and ghost atoms.  It is also why dumped atom
-coordinates can be slightly outside the simulation box.
-
-The box boundaries are then reset (if needed) via the reset\_box()
-method of the Domain class, e.g. if box boundaries are shrink-wrapped
-to current particle coordinates.  A change in the box size or shape
-requires internal information for communicating ghost atoms (Comm
-class) and neighbor list bins (Neighbor class) be updated.  The
-setup() method of the Comm class and setup\_bins() method of the
-Neighbor class perform the update.
-
-The code is now ready to migrate atoms that have left a processor's
-geometric sub-domain to new processors.  The exchange() method of the
-Comm class performs this operation.  The borders() method of the Comm
-class then identifies ghost atoms surrounding each processor's
-sub-domain and communicates ghost atom information to neighboring
-processors.  It does this by looping over all the atoms owned by a
-processor to make lists of those to send to each neighbor processor.
-On subsequent timesteps, the lists are used by the
-Comm::forward\_comm() method.
-
-Fixes with a pre\_neighbor() method are then called.  These typically
-re-build some data structure stored by the fix that depends on the
-current atoms owned by each processor.
-
-Now that each processor has a current list of its owned and ghost
-atoms, LAMMPS is ready to rebuild neighbor lists via the build()
-method of the Neighbor class.  This is typically done by binning all
-owned and ghost atoms, and scanning a stencil of bins around each
-owned atom's bin to make a Verlet list of neighboring atoms within the
-force cutoff plus neighbor skin distance.
-
-In the next portion of the timestep, all interaction forces between
-particles are computed, after zeroing the per-atom force vector via
-the force\_clear() method.  If the newton flag is set to ``on'' by the
-newton command, forces on both owned and ghost atoms are calculated.
-
-Pairwise forces are calculated first, which enables the global virial
-(if requested) to be calculated cheaply (at the end of the
-Pair::compute() method), by a dot product of atom coordinates and
-forces.  By including owned and ghost atoms in the dot product, the
-effect of periodic boundary conditions is correctly accounted for.
-Molecular topology interactions (bonds, angles, dihedrals, impropers)
-are calculated next.  The final contribution is from long-range
-Coulombic interactions, invoked by the KSpace class.
-
-If the newton flag is on, forces on ghost atoms are communicated and
-summed back to their corresponding owned atoms.  The reverse\_comm()
-method of the Comm class performs this operation, which is essentially
-the inverse operation of sending copies of owned atom coordinates to
-other processor's ghost atoms.
-
-At this point in the timestep, the total force on each atom is known.
-Additional force constraints (external forces, SHAKE, etc) are applied
-by Fixes that have a post\_force() method.  The second half of the
-velocity-Verlet integration is then performed (another half-step
-update of the velocities) via fixes like nve, nvt, npt.
-
-At the end of the timestep, fixes that define an end\_of\_step()
-method are invoked.  These typically perform a diagnostic calculation,
-e.g. the ave/time and ave/spatial fixes.  The final operation of the
-timestep is to perform any requested output, via the write() method of
-the Output class.  There are 3 kinds of LAMMPS output: thermodynamic
-output to the screen and log file, snapshots of atom data to a dump
-file, and restart files.  See the thermo\_style, dump, and restart
-commands for more details.
-
-The iteration performed by an energy minimization is similar to the
-dynamics timestep of Fig \ref{fig:verlet}.  Forces are computed,
-neighbor lists are built as needed, atoms migrate to new processors,
-and atom coordinates and forces are communicated to neighboring
-processors.  The only difference is what Fix class operations are
-invoked when.  Only a subset of LAMMPS fixes are useful during energy
-minimization, as explained in their individual doc pages.  The
-relevant Fix class methods are min\_pre\_exchange(),
-min\_pre\_force(), and min\_post\_force().  Each is invoked at the
-appropriate place within the minimization iteration.  For example, the
-min\_post\_force() method is analogous to the post\_force() method for
-dynamics; it is used to alter or constrain forces on each atom, which
-affects the minimization procedure.
-
-\pagebreak
-\section{Extending LAMMPS}
-
-The Section\_modify.html file in the doc directory of
-the LAMMPS distribution gives an overview of how LAMMPS can
-be extended by writing new classes that derive from existing
-parent classes in LAMMPS.  Here, some specific coding
-details are provided for writing a new fix.
-
-\subsection{New fixes}
-
-(this section provided by Kirill Lykov)
-\vspace{0.25cm}
-
-Writing fixes is a flexible way of extending LAMMPS.  Users can
-implement many things using fixes:
-
-\begin{itemize}
-\item changing particles attributes (positions, velocities, forces, etc.).
-Example: FixFreeze.
-\item reading/writing data. Example: FixRestart.
-\item implementing boundary conditions. Example: FixWall.
-\item saving information about particles for future use (previous positions,
-for instance). Example: FixStoreState.
-\end{itemize}
-
-All fixes are derived from class Fix and must have constructor with the
-signature: FixMine(class LAMMPS *, int, char **).
-
-Every fix must be registered in LAMMPS by writing the following lines
-of code in the header before include guards:
-
- \begin{center}
- \begin{verbatim}
-#ifdef FIX_CLASS
-FixStyle(your/fix/name,FixMine)
-#else
-  \end{verbatim}
- \end{center}
-
-Where ``your/fix/name'' is a name of your fix in the script and FixMine
-is the name of the class. This code allows LAMMPS to find your fix
-when it parses input script. In addition, your fix header must be
-included in the file ``style\_fix.h''. In case if you use LAMMPS make,
-this file is generated automatically - all files starting with prefix
-fix\_ are included, so call your header the same way. Otherwise, don't
-forget to add your include into ``style\_fix.h''.
-
-Let's write a simple fix which will print average velocity at the end
-of each timestep. First of all, implement a constructor:
-
- \begin{center}
- \begin{verbatim}
-FixPrintVel::FixPrintVel(LAMMPS *lmp, int narg, char **arg)
-: Fix(lmp, narg, arg)
-{
-  if (narg < 4)
-      error->all(FLERR,"Illegal fix print command");
-
-  nevery = atoi(arg[3]);
-  if (nevery <= 0)
-      error->all(FLERR,"Illegal fix print command");
-}
-  \end{verbatim}
- \end{center}
-
-In the constructor you should parse your fix arguments which are
-specified in the script. All fixes have pretty the same syntax: fix
-[fix\_identifier] [group\_name] [fix\_name] [fix\_arguments]. The
-first 3 parameters are parsed by Fix class constructor, while
-[fix\_arguments] should be parsed by you. In our case, we need to
-specify how often we want to print an average velocity. For instance,
-once in 50 timesteps: fix 1 print/vel 50. There is a special variable
-in Fix class called nevery which specifies how often method
-end\_of\_step() is called. Thus all we need to do is just set it up.
-
-The next method we need to implement is setmask():
-\begin{center}
-\begin{verbatim}
-int FixPrintVel::setmask()
-{
-  int mask = 0;
-  mask |= FixConst::END_OF_STEP;
-  return mask;
-}
-\end{verbatim}
-\end{center}
-
-Here user specifies which methods of your fix should be called during
-the execution. For instance, END\_OF\_STEP corresponds to the
-end\_of\_step() method. Overall, there are 8 most important methods,
-methods are called in predefined order during the execution of the
-verlet algorithm as was mentioned in the Section 3:
-
-\begin{itemize}
-\item initial\_integrate()
-\item post\_integrate()
-\item pre\_exchange()
-\item pre\_neighbor()
-\item pre\_force()
-\item post\_force()
-\item final\_integrate()
-\item end\_of\_step()
-\end{itemize}
-
-Fix developer must understand when he wants to execute his code.  In
-case if we want to write FixPrintVel, we need only end\_of\_step():
-
-\begin{center}
-\begin{verbatim}
-void FixPrintVel::end_of_step()
-{
-  // for add3, scale3
-  using namespace MathExtra;
-
-  double** v = atom->v;
-  int nlocal = atom->nlocal;
-  double localAvgVel[4]; // 4th element for particles count
-  memset(localAvgVel, 0, 4 * sizeof(double));
-  for (int particleInd = 0; particleInd < nlocal; ++particleInd) {
-    add3(localAvgVel, v[particleInd], localAvgVel);
-  }
-  localAvgVel[3] = nlocal;
-  double globalAvgVel[4];
-  memset(globalAvgVel, 0, 4 * sizeof(double));
-  MPI_Allreduce(localAvgVel, globalAvgVel, 4, MPI_DOUBLE, MPI_SUM, world);
-  scale3(1.0 / globalAvgVel[3], globalAvgVel);
-  if (comm->me == 0) {
-    printf("\%e, \%e, \%e\n",
-      globalAvgVel[0], globalAvgVel[1], globalAvgVel[2]);
-  }
-}
-\end{verbatim}
-\end{center}
-
-In the code above, we use MathExtra routines defined in
-``math\_extra.h''.  There are bunch of math functions to work with
-arrays of doubles as with math vectors.
-
-In this code we use an instance of Atom class. This object is stored
-in the Pointers class (see ``pointers.h''). This object contains all
-global information about the simulation system. Data from Pointers
-class available to all classes inherited from it using protected
-inheritance. Hence when you write you own class, which is going to use
-LAMMPS data, don't forget to inherit from Pointers.  When writing
-fixes we inherit from class Fix which is inherited from Pointers so
-there is no need to inherit from it directly.
-
-The code above computes average velocity for all particles in the
-simulation.  Yet you have one unused parameter in fix call from the
-script - [group\_name].  This parameter specifies the group of atoms
-used in the fix. So we should compute average for all particles in the
-simulation if group\_name == all, but it can be any group. The group
-information is specified by groupbit which is defined in class Fix:
-
-\begin{center}
-\begin{verbatim}
-for (int particleInd = 0; particleInd < nlocal; ++particleInd) {
-  if (atom->mask[particleInd] & groupbit) {
-  //Do all job here
-  }
-}
-\end{verbatim}
-\end{center}
-
-Class Atom encapsulates atoms positions, velocities, forces, etc. User
-can access them using particle index. Note, that particle indexes are
-usually changed every timestep because of sorting.
-
-Lets consider another Fix example. We want to have a fix which stores
-atoms position from previous time step in your fix. The local atoms
-indexes will not be valid on the next iteration. In order to handle
-this situation there are several methods which should be implemented:
-
-\begin{itemize}
-\item \verb|double memory_usage| - return how much memory fix uses
-\item \verb|void grow_arrays(int)| - do reallocation of the per particle arrays
-  in your fix
-\item \verb|void copy_arrays(int i, int j, int delflag)| - copy i-th per-particle
-  information to j-th. Used when atoms sorting is performed. if delflag is set
-  and atom j owns a body, move the body information to atom i.
-\item \verb|void set_arrays(int i)| - sets i-th particle related information to zero
-\end{itemize}
-
-Note, that if your class implements these methods, it must call add calls of
-add\_callback and delete\_callback to constructor and destructor:
-
-\begin{center}
-\begin{verbatim}
-FixSavePos::FixSavePos(LAMMPS *lmp, int narg, char **arg)  {
-  //...
-  atom->add_callback(0);
-}
-
-FixSavePos::~FixSavePos() {
-  atom->delete_callback(id, 0);
-}
-\end{verbatim}
-\end{center}
-
-Since we want to store positions of atoms from previous timestep, we
-need to add double** x to the header file. Than add allocation code to
-constructor:
-
-\verb|memory->create(this->x, atom->nmax, 3, "FixSavePos:x");|. Free memory
-at destructor: \verb|memory->destroy(x);|
-
-Finally, implement mentioned methods:
-
-\begin{center}
-\begin{verbatim}
-double FixSavePos::memory_usage()
-{
-  int nmax = atom->nmax;
-  double bytes = 0.0;
-  bytes += nmax * 3 * sizeof(double);
-  return bytes;
-}
-
-void FixSavePos::grow_arrays(int nmax)
-{
-    memory->grow(this->x, nmax, 3, "FixSavePos:x");
-}
-
-void FixSavePos::copy_arrays(int i, int j, int delflag)
-{
-    memcpy(this->x[j], this->x[i], sizeof(double) * 3);
-}
-
-void FixSavePos::set_arrays(int i)
-{
-    memset(this->x[i], 0, sizeof(double) * 3);
-}
-
-int FixSavePos::pack_exchange(int i, double *buf)
-{
-  int m = 0;
-  buf[m++] = x[i][0];
-  buf[m++] = x[i][1];
-  buf[m++] = x[i][2];
-
-  return m;
-}
-
-int FixSavePos::unpack_exchange(int nlocal, double *buf)
-{
-  int m = 0;
-  x[nlocal][0] = buf[m++];
-  x[nlocal][1] = buf[m++];
-  x[nlocal][2] = buf[m++];
-
-  return m;
-}
-\end{verbatim}
-\end{center}
-
-Now, a little bit about memory allocation. We used Memory class which
-is just a bunch of template functions for allocating 1D and 2D
-arrays. So you need to add include ``memory.h'' to have access to them.
-
-Finally, if you need to write/read some global information used in
-your fix to the restart file, you might do it by setting flag
-restart\_global = 1 in the constructor and implementing methods void
-write\_restart(FILE *fp) and void restart(char *buf).
-
-\end{document}

doc/src/Developer_flow.rst

@@ -0,0 +1,236 @@
+How a timestep works
+====================
+
+The first and most fundamental operation within LAMMPS to understand is
+how a timestep is structured.  Timestepping is performed by calling
+methods of the Integrate class instance within the Update class.  Since
+Integrate is a base class, it will point to an instance of a derived
+class corresponding to what is selected by the :doc:`run_style
+<run_style>` input script command.
+
+In this section, the timestep implemented by the Verlet class is
+described.  A similar timestep protocol is implemented by the Respa
+class, for the r-RESPA hierarchical timestepping method.
+
+The Min base class performs energy minimization, so does not perform a
+literal timestep.  But it has logic similar to what is described here,
+to compute forces and invoke fixes at each iteration of a minimization.
+Differences between time integration and minimization are highlighted at
+the end of this section.
+
+The Verlet class is encoded in the ``src/verlet.cpp`` and ``verlet.h``
+files.  It implements the velocity-Verlet timestepping algorithm.  The
+workhorse method is ``Verlet::run()``, but first we highlight several
+other methods in the class.
+
+- The ``init()`` method is called at the beginning of each dynamics
+  run.  It simply sets some internal flags, based on user settings in
+  other parts of the code.
+
+- The ``setup()`` or ``setup_minimal()`` methods are also called before
+  each run.  The velocity-Verlet method requires current forces be
+  calculated before the first timestep, so these routines compute
+  forces due to all atomic interactions, using the same logic that
+  appears in the timestepping described next.  A few fixes are also
+  invoked, using the mechanism described in the next section.  Various
+  counters are also initialized before the run begins.  The
+  ``setup_minimal()`` method is a variant that has a flag for performing
+  less setup.  This is used when runs are continued and information
+  from the previous run is still valid.  For example, if repeated
+  short LAMMPS runs are being invoked, interleaved by other commands,
+  via the *pre no* and *every* options of the run command, the
+  ``setup_minimal()`` method is used.
+
+- The ``force_clear()`` method initializes force and other arrays to
+  zero before each timestep, so that forces (torques, etc) can be
+  accumulated.
+
+Now for the ``Verlet::run()`` method.  Its basic structure in hi-level pseudo
+code is shown below.  In the actual code in ``src/verlet.cpp`` some of
+these operations are conditionally invoked.
+
+.. code-block:: python
+
+   loop over N timesteps:
+     if timeout condition: break
+     ev_set()
+
+     fix->initial_integrate()
+     fix->post_integrate()
+
+     nflag = neighbor->decide()
+     if nflag:
+       fix->pre_exchange()
+       domain->pbc()
+       domain->reset_box()
+       comm->setup()
+       neighbor->setup_bins()
+       comm->exchange()
+       comm->borders()
+       fix->pre_neighbor()
+       neighbor->build()
+       fix->post_neighbor()
+     else:
+       comm->forward_comm()
+
+     force_clear()
+     fix->pre_force()
+
+     pair->compute()
+     bond->compute()
+     angle->compute()
+     dihedral->compute()
+     improper->compute()
+     kspace->compute()
+
+     fix->pre_reverse()
+     comm->reverse_comm()
+
+     fix->post_force()
+     fix->final_integrate()
+     fix->end_of_step()
+
+     if any output on this step:
+       output->write()
+
+   # after loop
+   fix->post_run()
+
+
+The ``ev_set()`` method (in the parent Integrate class), sets two flags
+(*eflag* and *vflag*) for energy and virial computation.  Each flag
+encodes whether global and/or per-atom energy and virial should be
+calculated on this timestep, because some fix or variable or output will
+need it.  These flags are passed to the various methods that compute
+particle interactions, so that they either compute and tally the
+corresponding data or can skip the extra calculations if the energy and
+virial are not needed.  See the comments for the ``Integrate::ev_set()``
+method which document the flag values.
+
+At various points of the timestep, fixes are invoked,
+e.g. ``fix->initial_integrate()``.  In the code, this is actually done
+via the Modify class which stores all the Fix objects and lists of which
+should be invoked at what point in the timestep.  Fixes are the LAMMPS
+mechanism for tailoring the operations of a timestep for a particular
+simulation.  As described elsewhere, each fix has one or more methods,
+each of which is invoked at a specific stage of the timestep, as show in
+the timestep pseudo-code.  All the active fixes defined in an input
+script, that are flagged to have an ``initial_integrate()`` method are
+invoked at the beginning of each timestep.  Examples are :doc:`fix nve
+<fix_nve>` or :doc:`fix nvt or fix npt <fix_nh>` which perform the
+start-of-timestep velocity-Verlet integration operations to update
+velocities by a half-step, and coordinates by a full step.  The
+``post_integrate()`` method is next for operations that need to happen
+immediately after those updates.  Only a few fixes use this, e.g. to
+reflect particles off box boundaries in the :doc:`FixWallReflect class
+<fix_wall_reflect>`.
+
+The ``decide()`` method in the Neighbor class determines whether
+neighbor lists need to be rebuilt on the current timestep (conditions
+can be changed using the :doc:`neigh_modify every/delay/check
+<neigh_modify>` command.  If not, coordinates of ghost atoms are
+acquired by each processor via the ``forward_comm()`` method of the Comm
+class.  If neighbor lists need to be built, several operations within
+the inner if clause of the pseudo-code are first invoked.  The
+``pre_exchange()`` method of any defined fixes is invoked first.
+Typically this inserts or deletes particles from the system.
+
+Periodic boundary conditions are then applied by the Domain class via
+its ``pbc()`` method to remap particles that have moved outside the
+simulation box back into the box.  Note that this is not done every
+timestep, but only when neighbor lists are rebuilt.  This is so that
+each processor's sub-domain will have consistent (nearby) atom
+coordinates for its owned and ghost atoms.  It is also why dumped atom
+coordinates may be slightly outside the simulation box if not dumped
+on a step where the neighbor lists are rebuilt.
+
+The box boundaries are then reset (if needed) via the ``reset_box()``
+method of the Domain class, e.g. if box boundaries are shrink-wrapped to
+current particle coordinates.  A change in the box size or shape
+requires internal information for communicating ghost atoms (Comm class)
+and neighbor list bins (Neighbor class) be updated.  The ``setup()``
+method of the Comm class and ``setup_bins()`` method of the Neighbor
+class perform the update.
+
+The code is now ready to migrate atoms that have left a processor's
+geometric sub-domain to new processors.  The ``exchange()`` method of
+the Comm class performs this operation.  The ``borders()`` method of the
+Comm class then identifies ghost atoms surrounding each processor's
+sub-domain and communicates ghost atom information to neighboring
+processors.  It does this by looping over all the atoms owned by a
+processor to make lists of those to send to each neighbor processor.  On
+subsequent timesteps, the lists are used by the ``Comm::forward_comm()``
+method.
+
+Fixes with a ``pre_neighbor()`` method are then called.  These typically
+re-build some data structure stored by the fix that depends on the
+current atoms owned by each processor.
+
+Now that each processor has a current list of its owned and ghost
+atoms, LAMMPS is ready to rebuild neighbor lists via the ``build()``
+method of the Neighbor class.  This is typically done by binning all
+owned and ghost atoms, and scanning a stencil of bins around each
+owned atom's bin to make a Verlet list of neighboring atoms within the
+force cutoff plus neighbor skin distance.
+
+In the next portion of the timestep, all interaction forces between
+particles are computed, after zeroing the per-atom force vector via the
+``force_clear()`` method.  If the newton flag is set to *on* by the
+newton command, forces are added to both owned and ghost atoms, otherwise
+only to owned (aka local) atoms.
+
+Pairwise forces are calculated first, which enables the global virial
+(if requested) to be calculated cheaply (at O(N) cost instead of O(N**2)
+at the end of the ``Pair::compute()`` method), by a dot product of atom
+coordinates and forces.  By including owned and ghost atoms in the dot
+product, the effect of periodic boundary conditions is correctly
+accounted for.  Molecular topology interactions (bonds, angles,
+dihedrals, impropers) are calculated next (if supported by the current
+atom style).  The final contribution is from long-range Coulombic
+interactions, invoked by the KSpace class.
+
+The ``pre_reverse()`` method in fixes is used for operations that have to
+be done *before* the upcoming reverse communication (e.g. to perform
+additional data transfers or reductions for data computed during the
+force computation and stored with ghost atoms).
+
+If the newton flag is on, forces on ghost atoms are communicated and
+summed back to their corresponding owned atoms.  The ``reverse_comm()``
+method of the Comm class performs this operation, which is essentially
+the inverse operation of sending copies of owned atom coordinates to
+other processor's ghost atoms.
+
+At this point in the timestep, the total force on each (local) atom is
+known.  Additional force constraints (external forces, SHAKE, etc) are
+applied by Fixes that have a ``post_force()`` method.  The second half
+of the velocity-Verlet integration, ``final_integrate()`` is then
+performed (another half-step update of the velocities) via fixes like
+nve, nvt, npt.
+
+At the end of the timestep, fixes that contain an ``end_of_step()``
+method are invoked.  These typically perform a diagnostic calculation,
+e.g. the ave/time and ave/spatial fixes.  The final operation of the
+timestep is to perform any requested output, via the ``write()`` method
+of the Output class.  There are 3 kinds of LAMMPS output: thermodynamic
+output to the screen and log file, snapshots of atom data to a dump
+file, and restart files.  See the :doc:`thermo_style <thermo_style>`,
+:doc:`dump <dump>`, and :doc:`restart <restart>` commands for more
+details.
+
+The the flow of control during energy minimization iterations is
+similar to that of a molecular dynamics timestep.  Forces are computed,
+neighbor lists are built as needed, atoms migrate to new processors, and
+atom coordinates and forces are communicated to neighboring processors.
+The only difference is what Fix class operations are invoked when.  Only
+a subset of LAMMPS fixes are useful during energy minimization, as
+explained in their individual doc pages.  The relevant Fix class methods
+are ``min_pre_exchange()``, ``min_pre_force()``, and ``min_post_force()``.
+Each fix is invoked at the appropriate place within the minimization
+iteration.  For example, the ``min_post_force()`` method is analogous to
+the ``post_force()`` method for dynamics; it is used to alter or constrain
+forces on each atom, which affects the minimization procedure.
+
+After all iterations are completed there is a ``cleanup`` step which
+calls the ``post_run()`` method of fixes to perform operations only required
+at the end of a calculations (like freeing temporary storage or creating
+final outputs).

doc/src/Developer_org.rst

@@ -0,0 +1,250 @@
+LAMMPS 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 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
+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.
+
+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.
+
+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
+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.
+
+LAMMPS 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.
+
+.. _class-topology:
+.. figure:: JPG/lammps-classes.png
+
+   LAMMPS class topology
+
+   This figure shows some of the relations of the base classes of the
+   LAMMPS simulation package.  Full lines indicate that a class holds an
+   instance of the class it is pointing to; dashed lines point to
+   derived classes that are given as examples of what classes may be
+   instantiated during a LAMMPS run based on the input commands and
+   accessed through the API define by their respective base classes.  At
+   the core is the :cpp:class:`LAMMPS <LAMMPS_NS::LAMMPS>` class, which
+   holds pointers to class instances with specific purposes.  Those may
+   hold instances of other classes, sometimes directly, or only
+   temporarily, sometimes as derived classes or derived classes or
+   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
+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
+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
+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`.
+
+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.
+
+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
+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.
+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.
+
+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.
+
+For all those ``styles`` certain naming conventions are employed: for
+the fix nve command the class is called FixNVE and the 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
+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).
+
+
+More details on individual classes in the :ref:`class-topology` are as
+follows:
+
+- The Memory class handles allocation of all large vectors and arrays.
+
+- The Error class prints all 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 Input class reads and processes input input strings and files,
+  stores variables, and invokes :doc:`commands <Commands_all>`.
+
+- As discussed above, command style classes are directly derived from
+  the Pointers class. They provide input script commands that perform
+  one-time operations before/after/between simulations or which invoke a
+  simulation.  They are instantiated from within the Input class,
+  invoked, then immediately destructed.
+
+- The Finish class is instantiated to print statistics to the screen
+  after a simulation is performed, by commands like run and minimize.
+
+- The Special class walks the bond topology of a molecular system to
+  find first, second, third neighbors of each atom.  It is invoked by
+  several commands, like :doc:`read_data <read_data>`,
+  :doc:`read_restart <read_restart>`, or :doc:`replicate <replicate>`.
+
+- The Atom class stores per-atom properties associated with atom styles.
+  More precisely, they are allocated and managed by a class derived from
+  the AtomVec class, and the Atom class simply stores pointers to them.
+  The classes derived from AtomVec represent the different atom styles
+  and they are instantiated through the :doc:`atom_style <atom_style>`
+  command.
+
+- The Update class holds instances of an integrator and a minimizer
+  class.  The Integrate class is a parent style for the Verlet and
+  r-RESPA time integrators, as defined by the :doc:`run_style
+  <run_style>` command.  The Min class is a parent style for various
+  energy minimizers.
+
+- The Neighbor class builds and stores neighbor lists.  The NeighList
+  class stores a single list (for all atoms).  A NeighRequest class
+  instance is created by pair, fix, or compute styles when they need a
+  particular kind of neighbor list and use the NeighRequest properties
+  to select the neighbor list settings for the given request. There can
+  be multiple instances of the NeighRequest class and the Neighbor class
+  will try to optimize how they are computed by creating copies or
+  sub-lists where possible.
+
+- The Comm class performs inter-processor communication, typically of
+  ghost atom information.  This usually involves MPI message exchanges
+  with 6 neighboring processors in the 3d logical grid of processors
+  mapped to the simulation box. There are two :doc:`communication styles
+  <comm_style>` enabling different ways to do the domain decomposition.
+  Sometimes the Irregular class is used, when atoms may migrate to
+  arbitrary processors.
+
+- The Domain class stores the simulation box geometry, as well as
+  geometric Regions and any user definition of a Lattice.  The latter
+  are defined by the :doc:`region <region>` and :doc:`lattice <lattice>`
+  commands in an input script.
+
+- The Force class computes various forces between atoms.  The Pair
+  parent class is for non-bonded or pair-wise forces, which in LAMMPS
+  also includes many-body forces such as the Tersoff 3-body potential if
+  those are computed by walking pairwise neighbor lists.  The Bond,
+  Angle, Dihedral, Improper parent classes are styles for bonded
+  interactions within a static molecular topology.  The KSpace parent
+  class is for computing long-range Coulombic interactions.  One of its
+  child classes, PPPM, uses the FFT3D and Remap classes to redistribute
+  and communicate grid-based information across the parallel processors.
+
+- The Modify class stores lists of class instances derived from the
+  :doc:`Fix <fix>` and :doc:`Compute <compute>` base classes.
+
+- The Group class manipulates groups that atoms are assigned to via the
+  :doc:`group <group>` command.  It also has functions to compute
+  various attributes of groups of atoms.
+
+- The Output class is used to generate 3 kinds of output from a LAMMPS
+  simulation: thermodynamic information printed to the screen and log
+  file, dump file snapshots, and restart files.  These correspond to the
+  :doc:`Thermo <thermo_style>`, :doc:`Dump <dump>`, and
+  :doc:`WriteRestart <write_restart>` classes respectively.  The Dump
+  class is a base class with several derived classes implementing
+  various dump style variants.
+
+- The Timer class logs timing information, output at the end
+  of a run.
+
+.. TODO section on "Spatial decomposition and parallel operations"
+..       diagram of 3d processor grid, brick vs. tiled. local vs. ghost
+..       atoms, 6-way communication with pack/unpack functions,
+..       PBC as part of the communication
+
+.. TODO section on "Fixes, Computes, and Variables"
+..      how and when data is computed and provided and how it is
+..      referenced. flags in Fix/Compute/Variable classes tell
+..      style and amount of available data.
+

doc/src/Developer_utils.rst

@@ -0,0 +1,484 @@
+
+LAMMPS utility functions
+========================
+
+The ``utils`` sub-namespace inside the ``LAMMPS_NS`` namespace provides
+a collection of convenience functions and utilities that perform common
+tasks that are required repeatedly throughout the LAMMPS code like
+reading or writing to files with error checking or translation of
+strings into specific types of numbers with checking for validity.  This
+reduces redundant implementations and encourages consistent behavior.
+
+I/O with status check
+^^^^^^^^^^^^^^^^^^^^^
+
+These are wrappers around the corresponding C library calls like
+``fgets()`` or ``fread()``.  They will check if there were errors
+on reading or an unexpected end-of-file state was reached.  In that
+case, the functions will stop the calculation with an error message,
+indicating the name of the problematic file, if possible.
+
+----------
+
+.. doxygenfunction:: sfgets
+   :project: progguide
+
+.. doxygenfunction:: sfread
+   :project: progguide
+
+----------
+
+String to number conversions with validity check
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+These functions should be used to convert strings to numbers. They are
+are strongly preferred over C library calls like ``atoi()`` or
+``atof()`` since they check if the **entire** provided string is a valid
+(floating-point or integer) number, and will error out instead of
+silently returning the result of a partial conversion or zero in cases
+where the string is not a valid number.  This behavior allows to more
+easily detect typos or issues when processing input files.
+
+The *do_abort* flag should be set to ``true`` in case  this function
+is called only on a single MPI rank, as that will then trigger the
+a call to ``Error::one()`` for errors instead of ``Error::all()``
+and avoids a "hanging" calculation when run in parallel.
+
+Please also see :cpp:func:`is_integer() <LAMMPS_NS::utils::is_integer>`
+and :cpp:func:`is_double() <LAMMPS_NS::utils::is_double>` for testing
+strings for compliance without conversion.
+
+----------
+
+.. doxygenfunction:: numeric
+   :project: progguide
+
+.. doxygenfunction:: inumeric
+   :project: progguide
+
+.. doxygenfunction:: bnumeric
+   :project: progguide
+
+.. doxygenfunction:: tnumeric
+   :project: progguide
+
+
+String processing
+^^^^^^^^^^^^^^^^^
+
+The following are functions to help with processing strings
+and parsing files or arguments.
+
+----------
+
+.. doxygenfunction:: trim
+   :project: progguide
+
+.. doxygenfunction:: trim_comment
+   :project: progguide
+
+.. doxygenfunction:: count_words(const char *text)
+   :project: progguide
+
+.. doxygenfunction:: count_words(const std::string &text)
+   :project: progguide
+
+.. doxygenfunction:: count_words(const std::string &text, const std::string &separators)
+   :project: progguide
+
+.. doxygenfunction:: trim_and_count_words
+   :project: progguide
+
+.. doxygenfunction:: split_words
+   :project: progguide
+
+.. doxygenfunction:: strmatch
+   :project: progguide
+
+.. doxygenfunction:: is_integer
+   :project: progguide
+
+.. doxygenfunction:: is_double
+   :project: progguide
+
+File and path functions
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. doxygenfunction:: guesspath
+   :project: progguide
+
+.. doxygenfunction:: path_basename
+   :project: progguide
+
+.. doxygenfunction:: path_join
+   :project: progguide
+
+.. doxygenfunction:: file_is_readable
+   :project: progguide
+
+Potential file functions
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. doxygenfunction:: get_potential_file_path
+   :project: progguide
+
+.. doxygenfunction:: get_potential_date
+   :project: progguide
+
+.. doxygenfunction:: get_potential_units
+   :project: progguide
+
+.. doxygenfunction:: get_supported_conversions
+   :project: progguide
+
+.. doxygenfunction:: get_conversion_factor
+   :project: progguide
+
+.. doxygenfunction:: open_potential(const std::string &name, LAMMPS *lmp, int *auto_convert)
+   :project: progguide
+
+Argument processing
+^^^^^^^^^^^^^^^^^^^
+
+.. doxygenfunction:: bounds
+   :project: progguide
+
+.. doxygenfunction:: expand_args
+   :project: progguide
+
+Convenience functions
+^^^^^^^^^^^^^^^^^^^^^
+
+.. doxygenfunction:: logmesg
+   :project: progguide
+
+.. doxygenfunction:: getsyserror
+   :project: progguide
+
+.. doxygenfunction:: check_packages_for_style
+   :project: progguide
+
+.. doxygenfunction:: timespec2seconds
+   :project: progguide
+
+.. doxygenfunction:: date2num
+   :project: progguide
+
+Customized standard functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. doxygenfunction:: merge_sort
+   :project: progguide
+
+---------------------------
+
+Communication buffer coding with *ubuf*
+=========================================
+
+LAMMPS uses communication buffers where it collects data from various
+class instances and then exchanges the data with neighboring sub-domains.
+For simplicity those buffers are defined as ``double`` buffers and
+used for doubles and integer numbers. This presents a unique problem
+when 64-bit integers are used.  While the storage needed for a ``double``
+is also 64-bit, it cannot be used by a simple assignment.  To get around
+that limitation, LAMMPS uses the :cpp:union:`ubuf <LAMMPS_NS::ubuf>`
+union.  It is used in the various "pack" and "unpack" functions in the
+LAMMPS classes to store and retrieve integers that may be 64-bit from
+the communication buffers.
+
+---------------------------
+
+.. doxygenunion:: LAMMPS_NS::ubuf
+   :project: progguide
+
+---------------------------
+
+Tokenizer classes
+=================
+
+The purpose of the tokenizer classes is to simplify the recurring task
+of breaking lines of text down into words and/or numbers.
+Traditionally, LAMMPS code would be using the ``strtok()`` function from
+the C library for that purpose, but that function has two significant
+disadvantages: 1) it cannot be used concurrently from different LAMMPS
+instances since it stores its status in a global variable and 2) it
+modifies the string that it is processing.  These classes were
+implemented to avoid both of these issues and also to reduce the amount
+of code that needs to be written.
+
+The basic procedure is to create an instance of the tokenizer class with
+the string to be processed as an argument and then do a loop until all
+available tokens are read.  The constructor has a default set of
+separator characters, but that can be overridden. The default separators
+are all "whitespace" characters, i.e. the space character, the tabulator
+character, the carriage return character, the linefeed character, and
+the form feed character.
+
+.. code-block:: C++
+   :caption: Tokenizer class example listing entries of the PATH environment variable
+
+   #include "tokenizer.h"
+   #include <cstdlib>
+   #include <string>
+   #include <iostream>
+
+   using namespace LAMMPS_NS;
+
+   int main(int, char **)
+   {
+       const char *path = getenv("PATH");
+
+       if (path != nullptr) {
+           Tokenizer p(path,":");
+           while (p.has_next())
+               std::cout << "Entry: " << p.next() << "\n";
+       }
+       return 0;
+   }
+
+Most tokenizer operations cannot fail except for
+:cpp:func:`LAMMPS_NS::Tokenizer::next` (when used without first
+checking with :cpp:func:`LAMMPS_NS::Tokenizer::has_next`) and
+:cpp:func:`LAMMPS_NS::Tokenizer::skip`.  In case of failure, the class
+will throw an exception, so you may need to wrap the code using the
+tokenizer into a ``try`` / ``catch`` block to handle errors.  The
+:cpp:class:`LAMMPS_NS::ValueTokenizer` class may also throw an exception
+when a (type of) number is requested as next token that is not
+compatible with the string representing the next word.
+
+.. code-block:: C++
+   :caption: ValueTokenizer class example with exception handling
+
+   #include "tokenizer.h"
+   #include <cstdlib>
+   #include <string>
+   #include <iostream>
+
+   using namespace LAMMPS_NS;
+
+   int main(int, char **)
+   {
+       const char *text = "1 2 3 4 5 20.0 21 twentytwo 2.3";
+       double num1(0),num2(0),num3(0),num4(0);
+
+       ValueTokenizer t(text);
+       // read 4 doubles after skipping over 5 numbers
+       try {
+           t.skip(5);
+           num1 = t.next_double();
+           num2 = t.next_double();
+           num3 = t.next_double();
+           num4 = t.next_double();
+       } catch (TokenizerException &e) {
+           std::cout << "Reading numbers failed: " << e.what() << "\n";
+       }
+       std::cout << "Values: " << num1 << " " << num2 << " " << num3 << " " << num4 << "\n";
+       return 0;
+   }
+
+This code example should produce the following output:
+
+.. code-block::
+
+   Reading numbers failed: Not a valid floating-point number: 'twentytwo'
+   Values: 20 21 0 0
+
+----------
+
+.. doxygenclass:: LAMMPS_NS::Tokenizer
+   :project: progguide
+   :members:
+
+.. doxygenclass:: LAMMPS_NS::TokenizerException
+   :project: progguide
+   :members:
+
+.. doxygenclass:: LAMMPS_NS::ValueTokenizer
+   :project: progguide
+   :members:
+
+.. doxygenclass:: LAMMPS_NS::InvalidIntegerException
+   :project: progguide
+   :members: what
+
+.. doxygenclass:: LAMMPS_NS::InvalidFloatException
+   :project: progguide
+   :members: what
+
+----------
+
+File reader classes
+====================
+
+The purpose of the file reader classes is to simplify the recurring task
+of reading and parsing files. They can use the
+:cpp:class:`LAMMPS_NS::ValueTokenizer` class to process the read in
+text.  The :cpp:class:`LAMMPS_NS::TextFileReader` is a more general
+version while :cpp:class:`LAMMPS_NS::PotentialFileReader` is specialized
+to implement the behavior expected for looking up and reading/parsing
+files with potential parameters in LAMMPS.  The potential file reader
+class requires a LAMMPS instance, requires to be run on MPI rank 0 only,
+will use the :cpp:func:`LAMMPS_NS::utils::get_potential_file_path`
+function to look up and open the file, and will call the
+:cpp:class:`LAMMPS_NS::Error` class in case of failures to read or to
+convert numbers, so that LAMMPS will be aborted.
+
+.. code-block:: C++
+   :caption: Use of PotentialFileReader class in pair style coul/streitz
+
+    PotentialFileReader reader(lmp, file, "coul/streitz");
+    char * line;
+
+    while((line = reader.next_line(NPARAMS_PER_LINE))) {
+      try {
+        ValueTokenizer values(line);
+        std::string iname = values.next_string();
+
+        int ielement;
+        for (ielement = 0; ielement < nelements; ielement++)
+          if (iname == elements[ielement]) break;
+
+        if (nparams == maxparam) {
+          maxparam += DELTA;
+          params = (Param *) memory->srealloc(params,maxparam*sizeof(Param),
+                                              "pair:params");
+        }
+
+        params[nparams].ielement = ielement;
+        params[nparams].chi = values.next_double();
+        params[nparams].eta = values.next_double();
+        params[nparams].gamma = values.next_double();
+        params[nparams].zeta = values.next_double();
+        params[nparams].zcore = values.next_double();
+
+      } catch (TokenizerException & e) {
+        error->one(FLERR, e.what());
+      }
+      nparams++;
+    }
+
+A file that would be parsed by the reader code fragment looks like this:
+
+.. parsed-literal::
+
+   # DATE: 2015-02-19 UNITS: metal CONTRIBUTOR: Ray Shan CITATION: Streitz and Mintmire, Phys Rev B, 50, 11996-12003 (1994)
+   #
+   # X (eV)                J (eV)          gamma (1/\AA)   zeta (1/\AA)    Z (e)
+
+   Al      0.000000        10.328655       0.000000        0.968438        0.763905
+   O       5.484763        14.035715       0.000000        2.143957        0.000000
+
+
+----------
+
+.. doxygenclass:: LAMMPS_NS::TextFileReader
+   :project: progguide
+   :members:
+
+.. doxygenclass:: LAMMPS_NS::PotentialFileReader
+   :project: progguide
+   :members:
+
+----------
+
+Memory pool classes
+===================
+
+The memory pool classes are used for cases where otherwise many
+small memory allocations would be needed and where the data would
+be either all used or all freed.  One example for that is the
+storage of neighbor lists.  The memory management strategy is
+based on the assumption that allocations will be in chunks of similar
+sizes.  The allocation is then not done per individual call for a
+reserved chunk of memory, but for a "page" that can hold multiple
+chunks of data.  A parameter for the maximum chunk size must be
+provided, as that is used to determine whether a new page of memory
+must be used.
+
+The :cpp:class:`MyPage <LAMMPS_NS::MyPage>` class offers two ways to
+reserve a chunk: 1) with :cpp:func:`get() <LAMMPS_NS::MyPage::get>` the
+chunk size needs to be known in advance, 2) with :cpp:func:`vget()
+<LAMMPS_NS::MyPage::vget>` a pointer to the next chunk is returned, but
+its size is registered later with :cpp:func:`vgot()
+<LAMMPS_NS::MyPage::vgot>`.
+
+.. code-block:: C++
+   :caption: Example of using :cpp:class:`MyPage <LAMMPS_NS::MyPage>`
+
+      #include "my_page.h"
+      using namespace LAMMPS_NS;
+
+      MyPage<double> *dpage = new MyPage<double>;
+      // max size of chunk: 256, size of page: 10240 doubles (=81920 bytes)
+      dpage->init(256,10240);
+
+      double **build_some_lists(int num)
+      {
+          dpage->reset();
+          double **dlist = new double*[num];
+          for (int i=0; i < num; ++i) {
+              double *dptr = dpage.vget();
+              int jnum = 0;
+              for (int j=0; j < jmax; ++j) {
+                  // compute some dvalue for eligible loop index j
+                  dptr[j] = dvalue;
+                  ++jnum;
+              }
+              if (dpage.status() != 0) {
+                  // handle out of memory or jnum too large errors
+              }
+              dpage.vgot(jnum);
+              dlist[i] = dptr;
+          }
+          return dlist;
+      }
+
+----------
+
+.. doxygenclass:: LAMMPS_NS::MyPage
+   :project: progguide
+   :members:
+
+.. doxygenclass:: LAMMPS_NS::MyPoolChunk
+   :project: progguide
+   :members:
+
+----------
+
+Eigensolver functions
+=====================
+
+The ``MathEigen`` sub-namespace of the ``LAMMPS_NS`` namespace contains
+functions and classes for eigensolvers. Currently only the
+:cpp:func:`jacobi3 function <MathEigen::jacobi3>` is used in various
+places in LAMMPS.  That function is built on top of a group of more
+generic eigensolvers that are maintained in the ``math_eigen_impl.h``
+header file.  This header contains the implementation of three template
+classes:
+
+#. "Jacobi" calculates all of the eigenvalues and eigenvectors
+   of a dense, symmetric, real matrix.
+
+#. The "PEigenDense" class only calculates the principal eigenvalue
+   (ie. the largest or smallest eigenvalue), and its corresponding
+   eigenvector.  However it is much more efficient than "Jacobi" when
+   applied to large matrices (larger than 13x13).  PEigenDense also can
+   understand complex-valued Hermitian matrices.
+
+#. The "LambdaLanczos" class is a generalization of "PEigenDense" which can be
+   applied to arbitrary sparse matrices.
+
+The "math_eigen_impl.h" code is an amalgamation of `jacobi_pd
+<https://github.com/jewettaij/jacobi_pd>`_ by Andrew Jewett at Scripps
+Research (under CC0-1.0 license) and `Lambda Lanczos
+<https://github.com/mrcdr/lambda-lanczos>`_ by Yuya Kurebayashi at
+Tohoku University (under MIT license)
+
+----------
+
+.. doxygenfunction:: MathEigen::jacobi3(double const *const *mat, double *eval, double **evec)
+   :project: progguide
+
+.. doxygenfunction:: MathEigen::jacobi3(double const mat[3][3], double *eval, double evec[3][3])
+   :project: progguide
+

doc/src/Developer_write.rst

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

doc/src/Errors_bugs.rst

@@ -6,23 +6,25 @@ the steps outlined below:
 
  * Check the `New features and bug fixes
    <https://lammps.sandia.gov/bug.html>`_ section of the `LAMMPS WWW site
-   <lws_>`_ to see if the bug has already been addressed in a patch.
+   <https://lammps.sandia.gov>`_ or the
+   `GitHub Releases page <https://github.com/lammps/lammps/releases>`_ to
+   see if the bug has already been addressed in a patch release.
  * Check that your issue can be reproduced with the latest development
    version of LAMMPS.
  * Check the manual carefully to verify that the unexpected behavior you
    are observing is indeed in conflict with the documentation
- * Check the `GitHub Issue page <gip_>`_
+ * Check the `GitHub Issue page <https://github.com/lammps/lammps/issues>`_
    if your issue has already been reported and if it is still open.
- * Check the `GitHub Pull Requests page <https://github.com/lammps/pulls>`_
-   if there is already a fix for your bug pending.
+ * Check the `GitHub Pull Requests page <https://github.com/lammps/lammps/pulls>`_
+   to see if there is already a fix for your bug pending.
  * Check the `mailing list archives <https://lammps.sandia.gov/mail.html>`_
    to see if the issue has been discussed before.
 
 If none of these steps yields any useful information, please file a new
-bug report on the `GitHub Issue page <gip_>`_.  The website will offer
-you to select a suitable template with explanations and then you should
-replace those explanations with the information that you can provide to
-reproduce your issue.
+bug report on the `GitHub Issue page <https://github.com/lammps/lammps/issues>`_.
+The website will offer you to select a suitable template with explanations
+and then you should replace those explanations with the information that
+you can provide to reproduce your issue.
 
 The most useful thing you can do to help us verify and fix a bug is to
 isolate the problem.  Run it on the smallest number of atoms and fewest
@@ -33,7 +35,7 @@ Please avoid using binary restart files unless the issue requires it.
 In the latter case you should also include an input deck to quickly
 generate this restart from a data file or a simple additional input.
 This input deck can be used with tools like a debugger or `valgrind
-<valgrind_>`_ to further :doc:`debug the crash <Errors_debug>`.
+<https://valgrind.org>`_ to further :doc:`debug the crash <Errors_debug>`.
 
 You may also send an email to the LAMMPS mailing list at
 "lammps-users at lists.sourceforge.net" describing the problem with the
@@ -44,6 +46,3 @@ is overlooked and then forgotten.  Issues on GitHub have to be explicitly
 closed, so that will *guarantee* that at least one LAMMPS developer will
 have looked at it.
 
-.. _lws: https://lammps.sandia.gov
-.. _gip: https://github.com/lammps/issues
-.. _valgrind: https://valgrind.org

doc/src/Errors_common.rst

@@ -48,8 +48,10 @@ to see it on the screen.  If you get an error like "Invalid ...
 style", with ... being fix, compute, pair, etc, it means that you
 mistyped the style name or that the command is part of an optional
 package which was not compiled into your executable.  The list of
-available styles in your executable can be listed by using :doc:`the -h command-line swith <Run_options>`.  The installation and
-compilation of optional packages is explained on the :doc:`Build packages <Build_package>` doc page.
+available styles in your executable can be listed by using
+:doc:`the -h command-line switch <Run_options>`.  The installation and
+compilation of optional packages is explained on the
+:doc:`Build packages <Build_package>` doc page.
 
 For a given command, LAMMPS expects certain arguments in a specified
 order.  If you mess this up, LAMMPS will often flag the error, but it

doc/src/Errors_messages.rst

@@ -502,10 +502,10 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
 *Bond/react: Unknown section in map file*
    Please ensure reaction map files are properly formatted.
 
-*Bond/react: Atom affected by reaction too close to template edge*
+*Bond/react: Atom/Bond type affected by reaction too close to template edge*
    This means an atom which changes type or connectivity during the
    reaction is too close to an 'edge' atom defined in the map
-   file. This could cause incorrect assignment of bonds, angle, etc.
+   file.  This could cause incorrect assignment of bonds, angle, etc.
    Generally, this means you must include more atoms in your templates,
    such that there are at least two atoms between each atom involved in
    the reaction and an edge atom.
@@ -1903,6 +1903,12 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
 *Compute %s does not allow use of dynamic group*
    Dynamic groups have not yet been enabled for this compute.
 
+*Compute for fix pafi does not calculate a local array*
+   Self-explanatory.
+
+*Compute for fix pafi must have 9 fields per atom*
+   Self-explanatory.
+
 *Compute ID for compute chunk /atom does not exist*
    Self-explanatory.
 
@@ -2999,9 +3005,6 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
 *Dump image line requires atom style line*
    Self-explanatory.
 
-*Dump image persp option is not yet supported*
-   Self-explanatory.
-
 *Dump image requires one snapshot per file*
    Use a "\*" in the filename.
 
@@ -5102,9 +5105,6 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
    The file produced by dump image cannot be binary and must
    be for a single processor.
 
-*Invalid dump image persp value*
-   Persp value must be >= 0.0.
-
 *Invalid dump image theta value*
    Theta must be between 0.0 and 180.0 inclusive.
 
@@ -5702,6 +5702,9 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
 *Molecule file has dihedrals but no ndihedrals setting*
    Self-explanatory.
 
+*Molecule file has fragments but no nfragments setting*
+   Self-explanatory.
+
 *Molecule file has impropers but no nimpropers setting*
    Self-explanatory.
 
@@ -5711,6 +5714,9 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
 *Molecule file has no Body Integers section*
    Self-explanatory.
 
+*Molecule file has no Fragments section*
+   Self-explanatory.
+
 *Molecule file has special flags but no bonds*
    Self-explanatory.
 
@@ -8104,9 +8110,6 @@ keyword to allow for additional bonds to be formed
 *Variable for dump image center is invalid style*
    Must be an equal-style variable.
 
-*Variable for dump image persp is invalid style*
-   Must be an equal-style variable.
-
 *Variable for dump image phi is invalid style*
    Must be an equal-style variable.
 
@@ -8247,9 +8250,6 @@ keyword to allow for additional bonds to be formed
 *Variable name for dump image center does not exist*
    Self-explanatory.
 
-*Variable name for dump image persp does not exist*
-   Self-explanatory.
-
 *Variable name for dump image phi does not exist*
    Self-explanatory.
 

doc/src/Examples.rst

@@ -27,7 +27,7 @@ be quickly post-processed into a movie using commands described on the
 :doc:`dump image <dump_image>` doc page.
 
 Animations of many of the examples can be viewed on the Movies section
-of the `LAMMPS web site <lws_>`_.
+of the `LAMMPS web site <https://lammps.sandia.gov/movies.html>`_.
 
 There are two kinds of sub-directories in the examples folder.  Lower
 case named directories contain one or a few simple, quick-to-run
@@ -223,4 +223,3 @@ instructions.  See the :doc:`Packages_details <Packages_details>` doc
 page for more info on specific USER packages.
 
 .. _openkim: https://openkim.org
-.. _lws: https://lammps.sandia.gov

doc/src/Fortran.rst

@@ -0,0 +1,211 @@
+The ``LIBLAMMPS`` Fortran Module
+********************************
+
+The ``LIBLAMMPS`` module provides an interface to call LAMMPS from a
+Fortran code.  It is based on the LAMMPS C-library interface and
+requires a Fortran 2003 compatible compiler to be compiled.
+
+While C libraries have a defined binary interface (ABI) and can thus be
+used from multiple compiler versions from different vendors for as long
+as they are compatible with the hosting operating system, the same is
+not true for Fortran codes.  Thus the LAMMPS Fortran module needs to be
+compiled alongside the code using it from the source code in
+``fortran/lammps.f90``.  When linking, you also need to
+:doc:`link to the LAMMPS library <Build_link>`.  A typical command line
+for a simple program using the Fortran interface would be:
+
+.. code-block:: bash
+
+   mpifort -o testlib.x  lammps.f90 testlib.f90 -L. -llammps
+
+Please note, that the MPI compiler wrapper is only required when the
+calling the library from an MPI parallel code.  Please also note the order
+of the source files: the lammps.f90 file needs to be compiled first,
+since it provides the ``LIBLAMMPS`` module that is imported by the
+Fortran code using the interface.
+
+.. versionadded:: 9Oct2020
+
+.. admonition:: Work in Progress
+   :class: note
+
+   This Fortran module is work in progress and only the documented
+   functionality is currently available. The final implementation should
+   cover the entire range of functionality available in the C and
+   Python library interfaces.
+
+.. note::
+
+   A contributed (and complete!) Fortran interface that is more
+   closely resembling the C-library interface is available
+   in the ``examples/COUPLE/fortran2`` folder.  Please see the
+   ``README`` file in that folder for more information about that
+   Fortran interface and how to contact its author and maintainer.
+
+----------
+
+Creating or deleting a LAMMPS object
+************************************
+
+With the Fortran interface the creation of a :cpp:class:`LAMMPS
+<LAMMPS_NS::LAMMPS>` instance is included in the constructor for
+creating the :f:func:`lammps` derived type.  To import the definition of
+that type and its type bound procedures you need to add a ``USE
+LIBLAMMPS`` statement.  Internally it will call either
+:cpp:func:`lammps_open_fortran` or :cpp:func:`lammps_open_no_mpi` from
+the C library API to create the class instance.  All arguments are
+optional and :cpp:func:`lammps_mpi_init` will be called automatically,
+if it is needed.  Similarly, a possible call to :cpp:func:`lammps_finalize`
+is integrated into the :f:func:`close` function and triggered with
+the optional logical argument set to ``.true.``. Here is a simple example:
+
+.. code-block:: fortran
+
+   PROGRAM testlib
+     USE LIBLAMMPS                 ! include the LAMMPS library interface
+     TYPE(lammps)     :: lmp       ! derived type to hold LAMMPS instance
+     CHARACTER(len=*), DIMENSION(*), PARAMETER :: args = &
+         [ CHARACTER(len=12) :: 'liblammps', '-log', 'none' ]
+
+     ! create a LAMMPS instance (and initialize MPI)
+     lmp = lammps(args)
+     ! get and print numerical version code
+     PRINT*, 'LAMMPS Version: ', lmp%version()
+     ! delete LAMMPS instance (and shuts down MPI)
+     CALL lmp%close(.true.)
+
+   END PROGRAM testlib
+
+--------------------
+
+Executing LAMMPS commands
+=========================
+
+Once a LAMMPS instance is created, it is possible to "drive" the LAMMPS
+simulation by telling LAMMPS to read commands from a file, or pass
+individual or multiple commands from strings or lists of strings.  This
+is done similar to how it is implemented in the `C-library
+<pg_lib_execute>` interface. Before handing off the calls to the
+C-library interface, the corresponding Fortran versions of the calls
+(:f:func:`file`, :f:func:`command`, :f:func:`commands_list`, and
+:f:func:`commands_string`) have to make a copy of the strings passed as
+arguments so that they can be modified to be compatible with the
+requirements of strings in C without affecting the original strings.
+Those copies are automatically deleted after the functions return.
+Below is a small demonstration of the uses of the different functions:
+
+.. code-block:: fortran
+
+   PROGRAM testcmd
+     USE LIBLAMMPS
+     TYPE(lammps)     :: lmp
+     CHARACTER(len=512) :: cmds
+     CHARACTER(len=40),ALLOCATABLE :: cmdlist(:)
+     CHARACTER(len=10) :: trimmed
+     INTEGER :: i
+
+     lmp = lammps()
+     CALL lmp%file('in.melt')
+     CALL lmp%command('variable zpos index 1.0')
+     ! define 10 groups of 10 atoms each
+     ALLOCATE(cmdlist(10))
+     DO i=1,10
+         WRITE(trimmed,'(I10)') 10*i
+         WRITE(cmdlist(i),'(A,I1,A,I10,A,A)')       &
+             'group g',i-1,' id ',10*(i-1)+1,':',ADJUSTL(trimmed)
+     END DO
+     CALL lmp%commands_list(cmdlist)
+     ! run multiple commands from multi-line string
+     cmds = 'clear' // NEW_LINE('A') //                       &
+         'region  box block 0 2 0 2 0 2' // NEW_LINE('A') //  &
+         'create_box 1 box' // NEW_LINE('A') //               &
+         'create_atoms 1 single 1.0 1.0 ${zpos}'
+     CALL lmp%commands_string(cmds)
+     CALL lmp%close()
+
+   END PROGRAM testcmd
+
+---------------
+
+The ``LIBLAMMPS`` module API
+****************************
+
+Below are the detailed descriptions of definitions and interfaces
+of the contents of the ``LIBLAMMPS`` Fortran interface to LAMMPS.
+
+.. f:type:: lammps
+
+   Derived type that is the general class of the Fortran interface.
+   It holds a reference to the :cpp:class:`LAMMPS <LAMMPS_NS::LAMMPS>` class instance
+   that any of the included calls are forwarded to.
+
+   :f c_ptr handle: reference to the LAMMPS class
+   :f close: :f:func:`close`
+   :f version: :f:func:`version`
+   :f file: :f:func:`file`
+   :f command: :f:func:`command`
+   :f commands_list: :f:func:`commands_list`
+   :f commands_string: :f:func:`commands_string`
+
+.. f:function:: lammps(args[,comm])
+
+   This is the constructor for the Fortran class and will forward
+   the arguments to a call to either :cpp:func:`lammps_open_fortran`
+   or :cpp:func:`lammps_open_no_mpi`. If the LAMMPS library has been
+   compiled with MPI support, it will also initialize MPI, if it has
+   not already been initialized before.
+
+   The *args* argument with the list of command line parameters is
+   optional and so it the *comm* argument with the MPI communicator.
+   If *comm* is not provided, ``MPI_COMM_WORLD`` is assumed. For
+   more details please see the documentation of :cpp:func:`lammps_open`.
+
+   :p character(len=*) args(*) [optional]: arguments as list of strings
+   :o integer comm [optional]: MPI communicator
+   :r lammps: an instance of the :f:type:`lammps` derived type
+
+.. f:subroutine:: close([finalize])
+
+   This method will close down the LAMMPS instance through calling
+   :cpp:func:`lammps_close`.  If the *finalize* argument is present and
+   has a value of ``.true.``, then this subroutine also calls
+   :cpp:func:`lammps_mpi_finalize`.
+
+   :o logical finalize [optional]: shut down the MPI environment of the LAMMPS library if true.
+
+.. f:function:: version()
+
+   This method returns the numeric LAMMPS version like :cpp:func:`lammps_version`
+
+   :r integer: LAMMPS version
+
+--------
+
+.. f:subroutine:: file(filename)
+
+   This method will call :cpp:func:`lammps_file` to have LAMMPS read
+   and process commands from a file.
+
+   :p character(len=*) filename: name of file with LAMMPS commands
+
+.. f:subroutine:: command(cmd)
+
+   This method will call :cpp:func:`lammps_command` to have LAMMPS
+   execute a single command.
+
+   :p character(len=*) cmd: single LAMMPS command
+
+.. f:subroutine:: commands_list(cmds)
+
+   This method will call :cpp:func:`lammps_commands_list` to have LAMMPS
+   execute a list of input lines.
+
+   :p character(len=*) cmd(*): list of LAMMPS input lines
+
+.. f:subroutine:: commands_string(str)
+
+   This method will call :cpp:func:`lammps_commands_string` to have LAMMPS
+   execute a block of commands from a string.
+
+   :p character(len=*) str: LAMMPS input in string
+

doc/src/Howto.rst

@@ -3,24 +3,12 @@ Howto discussions
 
 These doc pages describe how to perform various tasks with LAMMPS,
 both for users and developers.  The
-`glossary <https://lammps.sandia.gov>`_ website page also lists MD
+`glossary <https://lammps.sandia.gov/glossary.html>`_ website page also lists MD
 terminology with links to corresponding LAMMPS manual pages.  The
 example input scripts included in the examples directory of the LAMMPS
 distribution and highlighted on the :doc:`Examples <Examples>` doc page
 also show how to setup and run various kinds of simulations.
 
-Tutorials howto
-===============
-
-.. toctree::
-   :name: tutorials
-   :maxdepth: 1
-
-   Howto_cmake
-   Howto_github
-   Howto_pylammps
-   Howto_wsl
-
 General howto
 =============
 
@@ -94,3 +82,16 @@ Packages howto
    Howto_drude2
    Howto_manifold
    Howto_spins
+
+Tutorials howto
+===============
+
+.. toctree::
+   :name: tutorials
+   :maxdepth: 1
+
+   Howto_cmake
+   Howto_github
+   Howto_pylammps
+   Howto_wsl
+

doc/src/Howto_2d.rst

@@ -6,14 +6,14 @@ Use the :doc:`dimension <dimension>` command to specify a 2d simulation.
 Make the simulation box periodic in z via the :doc:`boundary <boundary>`
 command.  This is the default.
 
-If using the :doc:`create box <create_box>` command to define a
+If using the :doc:`create_box <create_box>` command to define a
 simulation box, set the z dimensions narrow, but finite, so that the
-create_atoms command will tile the 3d simulation box with a single z
-plane of atoms - e.g.
+:doc:`create_atoms <create_atoms>` command will fill the 3d simulation
+box with a single z plane of atoms - e.g.
 
 .. code-block:: LAMMPS
 
-   :doc:`create box <create_box>` 1 -10 10 -10 10 -0.25 0.25
+   create box 1 -10 10 -10 10 -0.25 0.25
 
 If using the :doc:`read data <read_data>` command to read in a file of
 atom coordinates, set the "zlo zhi" values to be finite but narrow,

doc/src/Howto_body.rst

@@ -32,9 +32,9 @@ thus how they can be used to compute pairwise body/body or
 bond/non-body (point particle) interactions.  More details of each
 style are described below.
 
-More styles may be added in the future.  See the :doc:`Modify body
-<Modify_body>` doc page for details on how to add a new body style to
-the code.
+More styles may be added in the future.  See the
+:doc:`page on creating new body styles <Modify_body>` for details on
+how to add a new body style to the code.
 
 ----------
 

doc/src/Howto_chunk.rst

@@ -198,7 +198,8 @@ explained on the :doc:`compute chunk/spread/atom <compute_chunk_spread_atom>` co
 
 (7) An example for using one set of per-chunk values for molecule
 chunks, to create a second set of micelle-scale chunks (clustered
-molecules, due to hydrophobicity), is explained on the :doc:`compute chunk/reduce <compute_reduce_chunk>` command doc page.
+molecules, due to hydrophobicity), is explained on the
+:doc:`compute reduce/chunk <compute_reduce_chunk>` command doc page.
 
 (8) An example for using one set of per-chunk values (dipole moment
 vectors) for molecule chunks, spreading the values to each atom in

doc/src/Howto_cmake.rst

@@ -191,19 +191,19 @@ You start the command ``ccmake ../cmake`` in the ``build`` folder.
 .. list-table::
 
    * - .. figure:: JPG/ccmake-initial.png
-          :target: JPG/ccmake-initial.png
+          :scale: 33%
           :align: center
 
           Initial ``ccmake`` screen
 
      - .. figure:: JPG/ccmake-config.png
-          :target: JPG/ccmake-config.png
+          :scale: 33%
           :align: center
 
           Configure output of ``ccmake``
 
      - .. figure:: JPG/ccmake-options.png
-          :target: JPG/ccmake-options.png
+          :scale: 33%
           :align: center
 
           Options screen of ``ccmake``
@@ -236,19 +236,19 @@ not required, it can also be entered from the GUI.
 .. list-table::
 
    * - .. figure:: JPG/cmake-gui-initial.png
-          :target: JPG/cmake-gui-initial.png
+          :scale: 40%
           :align: center
 
           Initial ``cmake-gui`` screen
 
      - .. figure:: JPG/cmake-gui-popup.png
-          :target: JPG/cmake-gui-popup.png
+          :scale: 60%
           :align: center
 
           Generator selection in ``cmake-gui``
 
      - .. figure:: JPG/cmake-gui-options.png
-          :target: JPG/cmake-gui-options.png
+          :scale: 40%
           :align: center
 
           Options screen of ``cmake-gui``
@@ -328,6 +328,8 @@ Some common LAMMPS specific variables
      - build LAMMPS with OpenMP support (default: ``on`` if compiler supports OpenMP fully, else ``off``)
    * - ``BUILD_TOOLS``
      - compile some additional executables from the ``tools`` folder (default: ``off``)
+   * - ``BUILD_LAMMPS_SHELL``
+     - compile the LAMMPS shell from the ``tools/lammps-shell`` folder (default: ``off``)
    * - ``BUILD_DOC``
      - include building the HTML format documentation for packaging/installing (default: ``off``)
    * - ``CMAKE_TUNE_FLAGS``

doc/src/Howto_couple.rst

@@ -12,96 +12,52 @@ LAMMPS can be coupled to other codes in at least 4 ways.  Each has
 advantages and disadvantages, which you will have to think about in the
 context of your application.
 
-----------
+1. Define a new :doc:`fix <fix>` command that calls the other code.  In
+   this scenario, LAMMPS is the driver code.  During timestepping,
+   the fix is invoked, and can make library calls to the other code,
+   which has been linked to LAMMPS as a library.  This is the way how the
+   :ref:`LATTE <PKG-LATTE>` package, which performs density-functional
+   tight-binding calculations using the `LATTE software <https://github.com/lanl/LATTE>`_
+   to compute forces, is hooked to LAMMPS.
+   See the :doc:`fix latte <fix_latte>` command for more details.
+   Also see the :doc:`Modify <Modify>` doc pages for info on how to
+   add a new fix to LAMMPS.
 
-(1) Define a new :doc:`fix <fix>` command that calls the other code.  In
-this scenario, LAMMPS is the driver code.  During its timestepping,
-the fix is invoked, and can make library calls to the other code,
-which has been linked to LAMMPS as a library.  This is the way the
-`POEMS <poems_>`_ package that performs constrained rigid-body motion on
-groups of atoms is hooked to LAMMPS.  See the :doc:`fix poems <fix_poems>` command for more details.  See the
-:doc:`Modify <Modify>` doc pages for info on how to add a new fix to
-LAMMPS.
+.. spacer
 
-.. _poems: http://www.rpi.edu/~anderk5/lab
+2. Define a new LAMMPS command that calls the other code.  This is
+   conceptually similar to method (1), but in this case LAMMPS and the
+   other code are on a more equal footing.  Note that now the other code
+   is not called during the timestepping of a LAMMPS run, but between
+   runs.  The LAMMPS input script can be used to alternate LAMMPS runs
+   with calls to the other code, invoked via the new command.  The
+   :doc:`run <run>` command facilitates this with its *every* option,
+   which makes it easy to run a few steps, invoke the command, run a few
+   steps, invoke the command, etc.
 
-----------
+   In this scenario, the other code can be called as a library, as in
+   1., or it could be a stand-alone code, invoked by a system() call
+   made by the command (assuming your parallel machine allows one or
+   more processors to start up another program).  In the latter case the
+   stand-alone code could communicate with LAMMPS through files that the
+   command writes and reads.
 
-(2) Define a new LAMMPS command that calls the other code.  This is
-conceptually similar to method (1), but in this case LAMMPS and the
-other code are on a more equal footing.  Note that now the other code
-is not called during the timestepping of a LAMMPS run, but between
-runs.  The LAMMPS input script can be used to alternate LAMMPS runs
-with calls to the other code, invoked via the new command.  The
-:doc:`run <run>` command facilitates this with its *every* option, which
-makes it easy to run a few steps, invoke the command, run a few steps,
-invoke the command, etc.
+   See the :doc:`Modify command <Modify_command>` doc page for info on how
+   to add a new command to LAMMPS.
 
-In this scenario, the other code can be called as a library, as in
-(1), or it could be a stand-alone code, invoked by a system() call
-made by the command (assuming your parallel machine allows one or more
-processors to start up another program).  In the latter case the
-stand-alone code could communicate with LAMMPS through files that the
-command writes and reads.
+.. spacer
 
-See the :doc:`Modify command <Modify_command>` doc page for info on how
-to add a new command to LAMMPS.
+3. Use LAMMPS as a library called by another code.  In this case the
+   other code is the driver and calls LAMMPS as needed.  Or a wrapper
+   code could link and call both LAMMPS and another code as libraries.
+   Again, the :doc:`run <run>` command has options that allow it to be
+   invoked with minimal overhead (no setup or clean-up) if you wish to
+   do multiple short runs, driven by another program.  Details about
+   using the library interface are given in the :doc:`library API
+   <Library>` documentation.
 
-----------
+.. spacer
 
-(3) Use LAMMPS as a library called by another code.  In this case the
-other code is the driver and calls LAMMPS as needed.  Or a wrapper
-code could link and call both LAMMPS and another code as libraries.
-Again, the :doc:`run <run>` command has options that allow it to be
-invoked with minimal overhead (no setup or clean-up) if you wish to do
-multiple short runs, driven by another program.
-
-Examples of driver codes that call LAMMPS as a library are included in
-the examples/COUPLE directory of the LAMMPS distribution; see
-examples/COUPLE/README for more details:
-
-* simple: simple driver programs in C++ and C which invoke LAMMPS as a
-  library
-* plugin: simple driver program in C which invokes LAMMPS as a plugin
-  from a shared library.
-* lammps_quest: coupling of LAMMPS and `Quest <quest_>`_, to run classical
-  MD with quantum forces calculated by a density functional code
-* lammps_spparks: coupling of LAMMPS and `SPPARKS <spparks_>`_, to couple
-  a kinetic Monte Carlo model for grain growth using MD to calculate
-  strain induced across grain boundaries
-
-.. _quest: http://dft.sandia.gov/Quest
-
-.. _spparks: http://www.sandia.gov/~sjplimp/spparks.html
-
-The :doc:`Build basics <Build_basics>` doc page describes how to build
-LAMMPS as a library.  Once this is done, you can interface with LAMMPS
-either via C++, C, Fortran, or Python (or any other language that
-supports a vanilla C-like interface).  For example, from C++ you could
-create one (or more) "instances" of LAMMPS, pass it an input script to
-process, or execute individual commands, all by invoking the correct
-class methods in LAMMPS.  From C or Fortran you can make function
-calls to do the same things.  See the :doc:`Python <Python_head>` doc
-pages for a description of the Python wrapper provided with LAMMPS
-that operates through the LAMMPS library interface.
-
-The files src/library.cpp and library.h contain the C-style interface
-to LAMMPS.  See the :doc:`Howto library <Howto_library>` doc page for a
-description of the interface and how to extend it for your needs.
-
-Note that the lammps_open() function that creates an instance of
-LAMMPS takes an MPI communicator as an argument.  This means that
-instance of LAMMPS will run on the set of processors in the
-communicator.  Thus the calling code can run LAMMPS on all or a subset
-of processors.  For example, a wrapper script might decide to
-alternate between LAMMPS and another code, allowing them both to run
-on all the processors.  Or it might allocate half the processors to
-LAMMPS and half to the other code and run both codes simultaneously
-before syncing them up periodically.  Or it might instantiate multiple
-instances of LAMMPS to perform different calculations.
-
-----------
-
-(4) Couple LAMMPS with another code in a client/server mode.  This is
-described on the :doc:`Howto client/server <Howto_client_server>` doc
-page.
+4. Couple LAMMPS with another code in a client/server mode.  This is
+   described on the :doc:`Howto client/server <Howto_client_server>` doc
+   page.

doc/src/Howto_drude.rst

@@ -29,7 +29,7 @@ molecular systems (:ref:`Lamoureux and Roux <howto-Lamoureux>`):
   to the total charge of the core atom).
 
 A detailed tutorial covering the usage of Drude induced dipoles in
-LAMMPS is on the :doc:`Howto drude2e <Howto_drude2>` doc page.
+LAMMPS is on the :doc:`here <Howto_drude2>`.
 
 As with the core-shell model, the cores and Drude particles should
 appear in the data file as standard atoms. The same holds for the

doc/src/Howto_drude2.rst

@@ -377,7 +377,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) <Lamoureux2>`, where the atoms progressively freeze and the
+: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:
 
@@ -456,7 +456,7 @@ NPT ensemble using Nose-Hoover thermostat:
 
 .. _Lamoureux2:
 
-**(Lamoureux)** Lamoureux and Roux, J Chem Phys, 119, 3025-3039 (2003)
+**(Lamoureux and Roux)** Lamoureux and Roux, J Chem Phys, 119, 3025-3039 (2003)
 
 .. _Schroeder:
 

doc/src/Howto_github.rst

@@ -20,7 +20,7 @@ work required by the LAMMPS developers. Consequently, creating a pull
 request will increase your chances to have your contribution included
 and will reduce the time until the integration is complete. For more
 information on the requirements to have your code included into LAMMPS
-please see the :doc:`Modify contribute <Modify_contribute>` doc page.
+please see :doc:`this page <Modify_contribute>`.
 
 ----------
 

doc/src/Howto_library.rst

@@ -2,241 +2,36 @@ Library interface to LAMMPS
 ===========================
 
 As described on the :doc:`Build basics <Build_basics>` doc page, LAMMPS
-can be built as a library, so that it can be called by another code,
-used in a :doc:`coupled manner <Howto_couple>` with other codes, or
-driven through a :doc:`Python interface <Python_head>`.
+can be built as a static or shared library, so that it can be called by
+another code, used in a :doc:`coupled manner <Howto_couple>` with other
+codes, or driven through a :doc:`Python interface <Python_head>`.
 
-All of these methodologies use a C-style interface to LAMMPS that is
-provided in the files src/library.cpp and src/library.h.  The
-functions therein have a C-style argument list, but contain C++ code
-you could write yourself in a C++ application that was invoking LAMMPS
-directly.  The C++ code in the functions illustrates how to invoke
-internal LAMMPS operations.  Note that LAMMPS classes are defined
-within a LAMMPS namespace (LAMMPS_NS) if you use them from another C++
-application.
+At the core of LAMMPS is the ``LAMMPS`` class which encapsulates the
+state of the simulation program through the state of the various class
+instances that it is composed of.  So a calculation using LAMMPS
+requires to create an instance of the ``LAMMPS`` class and then send it
+(text) commands, either individually or from a file, or perform other
+operations that modify the state stored inside that instance or drive
+simulations.  This is essentially what the ``src/main.cpp`` file does
+as well for the standalone LAMMPS executable with reading commands
+either from an input file or stdin.
 
-The examples/COUPLE and python/examples directories have example C++
-and C and Python codes which show how a driver code can link to LAMMPS
-as a library, run LAMMPS on a subset of processors, grab data from
-LAMMPS, change it, and put it back into LAMMPS.
+Creating a LAMMPS instance can be done by using C++ code directly or
+through a C-style interface library to LAMMPS that is provided in the
+files ``src/library.cpp`` and ``library.h``.  This
+:ref:`C language API <lammps_c_api>`, can be used from C and C++,
+and is also the basis for the :doc:`Python <Python_module>` and
+:doc:`Fortran <Fortran>` interfaces or wrappers included in the
+LAMMPS source code.
 
-Thread-safety
--------------
+The ``examples/COUPLE`` and ``python/examples`` directories contain some
+example programs written in C++, C, Fortran, and Python, which show how
+a driver code can link to LAMMPS as a library, run LAMMPS on a subset of
+processors (so the others are available to run some other code
+concurrently), grab data from LAMMPS, change it, and send it back into
+LAMMPS.
 
-LAMMPS has not initially been conceived as a thread-safe program, but
-over the years changes have been applied to replace operations that
-collide with creating multiple LAMMPS instances from multiple-threads
-of the same process with thread-safe alternatives.  This primarily
-applies to the core LAMMPS code and less so on add-on packages, especially
-when those packages require additional code in the *lib* folder,
-interface LAMMPS to Fortran libraries, or the code uses static variables
-(like the USER-COLVARS package.
+A detailed documentation of the available APIs and examples of how to
+use them can be found in the :doc:`Programmer Documentation
+<Library>` section of this manual.
 
-Another major issue to deal with is to correctly handle MPI.  Creating
-a LAMMPS instance requires passing an MPI communicator, or it assumes
-the MPI_COMM_WORLD communicator, which spans all MPI processor ranks.
-When creating multiple LAMMPS object instances from different threads,
-this communicator has to be different for each thread or else collisions
-can happen, or it has to be guaranteed, that only one thread at a time
-is active.  MPI communicators, however, are not a problem, if LAMMPS is
-compiled with the MPI STUBS library, which implies that there is no MPI
-communication and only 1 MPI rank.
-
-Provided APIs
--------------
-
-The file src/library.cpp contains the following functions for creating
-and destroying an instance of LAMMPS and sending it commands to
-execute.  See the documentation in the src/library.cpp file for
-details.
-
-.. note::
-
-   You can write code for additional functions as needed to define
-   how your code talks to LAMMPS and add them to src/library.cpp and
-   src/library.h, as well as to the :doc:`Python interface <Python_head>`.
-   The added functions can access or change any internal LAMMPS data you
-   wish.
-
-.. code-block:: c
-
-   void lammps_open(int, char **, MPI_Comm, void **)
-   void lammps_open_no_mpi(int, char **, void **)
-   void lammps_close(void *)
-   int lammps_version(void *)
-   void lammps_file(void *, char *)
-   char *lammps_command(void *, char *)
-   void lammps_commands_list(void *, int, char **)
-   void lammps_commands_string(void *, char *)
-   void lammps_free(void *)
-
-The lammps_open() function is used to initialize LAMMPS, passing in a
-list of strings as if they were :doc:`command-line arguments <Run_options>` when LAMMPS is run in stand-alone mode
-from the command line, and a MPI communicator for LAMMPS to run under.
-It returns a ptr to the LAMMPS object that is created, and which is
-used in subsequent library calls.  The lammps_open() function can be
-called multiple times, to create multiple instances of LAMMPS.
-
-LAMMPS will run on the set of processors in the communicator.  This
-means the calling code can run LAMMPS on all or a subset of
-processors.  For example, a wrapper script might decide to alternate
-between LAMMPS and another code, allowing them both to run on all the
-processors.  Or it might allocate half the processors to LAMMPS and
-half to the other code and run both codes simultaneously before
-syncing them up periodically.  Or it might instantiate multiple
-instances of LAMMPS to perform different calculations.
-
-The lammps_open_no_mpi() function is similar except that no MPI
-communicator is passed from the caller.  Instead, MPI_COMM_WORLD is
-used to instantiate LAMMPS, and MPI is initialized if necessary.
-
-The lammps_close() function is used to shut down an instance of LAMMPS
-and free all its memory.
-
-The lammps_version() function can be used to determined the specific
-version of the underlying LAMMPS code. This is particularly useful
-when loading LAMMPS as a shared library via dlopen(). The code using
-the library interface can than use this information to adapt to
-changes to the LAMMPS command syntax between versions. The returned
-LAMMPS version code is an integer (e.g. 2 Sep 2015 results in
-20150902) that grows with every new LAMMPS version.
-
-The lammps_file(), lammps_command(), lammps_commands_list(), and
-lammps_commands_string() functions are used to pass one or more
-commands to LAMMPS to execute, the same as if they were coming from an
-input script.
-
-Via these functions, the calling code can read or generate a series of
-LAMMPS commands one or multiple at a time and pass it through the library
-interface to setup a problem and then run it in stages.  The caller
-can interleave the command function calls with operations it performs,
-calls to extract information from or set information within LAMMPS, or
-calls to another code's library.
-
-The lammps_file() function passes the filename of an input script.
-The lammps_command() function passes a single command as a string.
-The lammps_commands_list() function passes multiple commands in a
-char\*\* list.  In both lammps_command() and lammps_commands_list(),
-individual commands may or may not have a trailing newline.  The
-lammps_commands_string() function passes multiple commands
-concatenated into one long string, separated by newline characters.
-In both lammps_commands_list() and lammps_commands_string(), a single
-command can be spread across multiple lines, if the last printable
-character of all but the last line is "&", the same as if the lines
-appeared in an input script.
-
-The lammps_free() function is a clean-up function to free memory that
-the library allocated previously via other function calls.  See
-comments in src/library.cpp file for which other functions need this
-clean-up.
-
-The file src/library.cpp also contains these functions for extracting
-information from LAMMPS and setting value within LAMMPS.  Again, see
-the documentation in the src/library.cpp file for details, including
-which quantities can be queried by name:
-
-.. code-block:: c
-
-   int lammps_extract_setting(void *, char *)
-   void *lammps_extract_global(void *, char *)
-   void lammps_extract_box(void *, double *, double *,
-                           double *, double *, double *, int *, int *)
-   void *lammps_extract_atom(void *, char *)
-   void *lammps_extract_compute(void *, char *, int, int)
-   void *lammps_extract_fix(void *, char *, int, int, int, int)
-   void *lammps_extract_variable(void *, char *, char *)
-
-The extract_setting() function returns info on the size
-of data types (e.g. 32-bit or 64-bit atom IDs) used
-by the LAMMPS executable (a compile-time choice).
-
-The other extract functions return a pointer to various global or
-per-atom quantities stored in LAMMPS or to values calculated by a
-compute, fix, or variable.  The pointer returned by the
-extract_global() function can be used as a permanent reference to a
-value which may change.  For the extract_atom() method, see the
-extract() method in the src/atom.cpp file for a list of valid per-atom
-properties.  New names could easily be added if the property you want
-is not listed.  For the other extract functions, the underlying
-storage may be reallocated as LAMMPS runs, so you need to re-call the
-function to assure a current pointer or returned value(s).
-
-.. code-block:: c
-
-   double lammps_get_thermo(void *, char *)
-   int lammps_get_natoms(void *)
-
-   int lammps_set_variable(void *, char *, char *)
-   void lammps_reset_box(void *, double *, double *, double, double, double)
-
-The lammps_get_thermo() function returns the current value of a thermo
-keyword as a double precision value.
-
-The lammps_get_natoms() function returns the total number of atoms in
-the system and can be used by the caller to allocate memory for the
-lammps_gather_atoms() and lammps_scatter_atoms() functions.
-
-The lammps_set_variable() function can set an existing string-style
-variable to a new string value, so that subsequent LAMMPS commands can
-access the variable.
-
-The lammps_reset_box() function resets the size and shape of the
-simulation box, e.g. as part of restoring a previously extracted and
-saved state of a simulation.
-
-.. code-block:: c
-
-   void lammps_gather_atoms(void *, char *, int, int, void *)
-   void lammps_gather_atoms_concat(void *, char *, int, int, void *)
-   void lammps_gather_atoms_subset(void *, char *, int, int, int, int *, void *)
-   void lammps_scatter_atoms(void *, char *, int, int, void *)
-   void lammps_scatter_atoms_subset(void *, char *, int, int, int, int *, void *)
-
-The gather functions collect peratom info of the requested type (atom
-coords, atom types, forces, etc) from all processors, and returns the
-same vector of values to each calling processor.  The scatter
-functions do the inverse.  They distribute a vector of peratom values,
-passed by all calling processors, to individual atoms, which may be
-owned by different processors.
-
-.. warning::
-
-   These functions are not compatible with the
-   -DLAMMPS_BIGBIG setting when compiling LAMMPS.  Dummy functions
-   that result in an error message and abort will be substituted
-   instead of resulting in random crashes and memory corruption.
-
-The lammps_gather_atoms() function does this for all N atoms in the
-system, ordered by atom ID, from 1 to N.  The
-lammps_gather_atoms_concat() function does it for all N atoms, but
-simply concatenates the subset of atoms owned by each processor.  The
-resulting vector is not ordered by atom ID.  Atom IDs can be requested
-by the same function if the caller needs to know the ordering.  The
-lammps_gather_subset() function allows the caller to request values
-for only a subset of atoms (identified by ID).
-For all 3 gather function, per-atom image flags can be retrieved in 2 ways.
-If the count is specified as 1, they are returned
-in a packed format with all three image flags stored in a single integer.
-If the count is specified as 3, the values are unpacked into xyz flags
-by the library before returning them.
-
-The lammps_scatter_atoms() function takes a list of values for all N
-atoms in the system, ordered by atom ID, from 1 to N, and assigns
-those values to each atom in the system.  The
-lammps_scatter_atoms_subset() function takes a subset of IDs as an
-argument and only scatters those values to the owning atoms.
-
-.. code-block:: c
-
-   void lammps_create_atoms(void *, int, tagint *, int *, double *, double *,
-                            imageint *, int)
-
-The lammps_create_atoms() function takes a list of N atoms as input
-with atom types and coords (required), an optionally atom IDs and
-velocities and image flags.  It uses the coords of each atom to assign
-it as a new atom to the processor that owns it.  This function is
-useful to add atoms to a simulation or (in tandem with
-lammps_reset_box()) to restore a previously extracted and saved state
-of a simulation.  Additional properties for the new atoms can then be
-assigned via the lammps_scatter_atoms() or lammps_extract_atom()
-functions.

doc/src/Howto_pylammps.rst

@@ -11,7 +11,7 @@ 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
-is discussed on the :doc:`Python library <Python_library>` doc page.
+is discussed on the :doc:`Python_head` doc page.
 
 Unlike the flat ``ctypes`` interface, PyLammps exposes a discoverable
 API.  It no longer requires knowledge of the underlying C++ code

doc/src/Howto_spherical.rst

@@ -114,7 +114,7 @@ will only rotate and experience torque if the force field computes
 such interactions.  These are the various :doc:`pair styles <pair_style>` that generate torque:
 
 * :doc:`pair_style gran/history <pair_gran>`
-* :doc:`pair_style gran/hertzian <pair_gran>`
+* :doc:`pair_style gran/hertz <pair_gran>`
 * :doc:`pair_style gran/no_history <pair_gran>`
 * :doc:`pair_style dipole/cut <pair_dipole>`
 * :doc:`pair_style gayberne <pair_gayberne>`

doc/src/Howto_thermostat.rst

@@ -42,12 +42,12 @@ particles.
 DPD thermostatting alters pairwise interactions in a manner analogous
 to the per-particle thermostatting of :doc:`fix langevin <fix_langevin>`.
 
-Any of the thermostatting fixes can use :doc:`temperature computes <Howto_thermostat>` that remove bias which has two
-effects.  First, the current calculated temperature, which is compared
-to the requested target temperature, is calculated with the velocity
-bias removed.  Second, the thermostat adjusts only the thermal
-temperature component of the particle's velocities, which are the
-velocities with the bias removed.  The removed bias is then added back
+Any of the thermostatting fixes can be instructed to use custom temperature
+computes that remove bias which has two effects:  first, the current
+calculated temperature, which is compared to the requested target temperature,
+is calculated with the velocity bias removed;  second, the thermostat adjusts
+only the thermal temperature component of the particle's velocities, which are
+the velocities with the bias removed.  The removed bias is then added back
 to the adjusted velocities.  See the doc pages for the individual
 fixes and for the :doc:`fix_modify <fix_modify>` command for
 instructions on how to assign a temperature compute to a
@@ -55,7 +55,24 @@ thermostatting fix.  For example, you can apply a thermostat to only
 the x and z components of velocity by using it in conjunction with
 :doc:`compute temp/partial <compute_temp_partial>`.  Of you could
 thermostat only the thermal temperature of a streaming flow of
-particles without affecting the streaming velocity, by using :doc:`compute temp/profile <compute_temp_profile>`.
+particles without affecting the streaming velocity, by using
+:doc:`compute temp/profile <compute_temp_profile>`.
+
+Below is a list of some custom temperature computes that can be used like that:
+
+* :doc:`compute_temp_asphere`
+* :doc:`compute_temp_body`
+* :doc:`compute_temp_chunk`
+* :doc:`compute_temp_com`
+* :doc:`compute_temp_deform`
+* :doc:`compute_temp_partial`
+* :doc:`compute_temp_profile`
+* :doc:`compute_temp_ramp`
+* :doc:`compute_temp_region`
+* :doc:`compute_temp_rotate`
+* :doc:`compute_temp_sphere`
+
+
 
 .. note::
 

doc/src/Howto_viscosity.rst

@@ -5,8 +5,8 @@ The shear viscosity eta of a fluid can be measured in at least 6 ways
 using various options in LAMMPS.  See the examples/VISCOSITY directory
 for scripts that implement the 5 methods discussed here for a simple
 Lennard-Jones fluid model and 1 method for SPC/E water model.
-Also, see the :doc:`Howto kappa <Howto_kappa>` doc page for an analogous discussion for
-thermal conductivity.
+Also, see the :doc:`page on calculating thermal conductivity <Howto_kappa>`
+for an analogous discussion for thermal conductivity.
 
 Eta is a measure of the propensity of a fluid to transmit momentum in
 a direction perpendicular to the direction of velocity or momentum

doc/src/Install.rst

@@ -23,7 +23,7 @@ need the source code.
 These are the files and sub-directories in the LAMMPS distribution:
 
 +------------+-------------------------------------------+
-| README     | text file                                 |
+| README     | Short description of the LAMMPS package   |
 +------------+-------------------------------------------+
 | LICENSE    | GNU General Public License (GPL)          |
 +------------+-------------------------------------------+
@@ -35,16 +35,20 @@ These are the files and sub-directories in the LAMMPS distribution:
 +------------+-------------------------------------------+
 | examples   | simple test problems                      |
 +------------+-------------------------------------------+
+| fortran    | Fortran wrapper for LAMMPS                |
++------------+-------------------------------------------+
 | lib        | additional provided or external libraries |
 +------------+-------------------------------------------+
 | potentials | interatomic potential files               |
 +------------+-------------------------------------------+
-| python     | Python wrapper on LAMMPS                  |
+| python     | Python wrappers for LAMMPS                |
 +------------+-------------------------------------------+
 | src        | source files                              |
 +------------+-------------------------------------------+
 | tools      | pre- and post-processing tools            |
 +------------+-------------------------------------------+
+| unittest   | sources and inputs for testing LAMMPS     |
++------------+-------------------------------------------+
 
 You will have all of these if you download source.  You will only have
 some of them if you download executables, as explained on the pages

doc/src/Install_git.rst

@@ -46,20 +46,19 @@ between them at any time using "git checkout <branch name>".)
 Once the command completes, your directory will contain the same files
 as if you unpacked a current LAMMPS tarball, with the exception, that
 the HTML documentation files are not included.  They can be fetched
-from the LAMMPS website by typing "make fetch" in the doc directory.
+from the LAMMPS website by typing ``make fetch`` in the doc directory.
 Or they can be generated from the content provided in doc/src by
-typing "make html" from the doc directory.
+typing ``make html`` from the doc directory.
 
 After initial cloning, as bug fixes and new features are added to
-LAMMPS, as listed on :doc:`this page <Errors_bugs>`, you can stay
-up-to-date by typing the following git commands from within the
-"mylammps" directory:
+LAMMPS you can stay up-to-date by typing the following git commands
+from within the "mylammps" directory:
 
 .. code-block:: bash
 
    $ git checkout unstable      # not needed if you always stay in this branch
-   $ git checkout stable        # use one of the 3 checkout commands
-   $ git checkout master
+   $ git checkout stable        # use one of these 3 checkout commands
+   $ git checkout master        # to choose the branch to follow
    $ git pull
 
 Doing a "pull" will not change any files you have added to the LAMMPS
@@ -70,8 +69,8 @@ repository file with your version of the file and tell you if there
 are any conflicts.  See the git documentation for details.
 
 If you want to access a particular previous release version of LAMMPS,
-you can instead "checkout" any version with a published tag. See the
-output of "git tag -l" for the list of tags.  The git command to do
+you can instead "check out" any version with a published tag. See the
+output of ``git tag -l`` for the list of tags.  The git command to do
 this is as follows.
 
 .. code-block:: bash
@@ -79,14 +78,14 @@ this is as follows.
    $ git checkout tagID
 
 Stable versions and what tagID to use for a particular stable version
-are discussed on :doc:`this page <Errors_bugs>`.  Note that this command
-will print some warnings, because in order to get back to the latest
-revision and to be able to update with "git pull" again, you first
-will need to first type "git checkout unstable" (or check out any
-other desired branch).
+are discussed on `this page <https://lammps.sandia.gov/bug.html#version>`_.
+Note that this command will print some warnings, because in order to get
+back to the latest revision and to be able to update with ``git pull``
+again, you will need to do ``git checkout unstable`` (or
+check out any other desired branch) first.
 
-Once you have updated your local files with a "git pull" (or "git
-checkout"), you still need to re-build LAMMPS if any source files have
+Once you have updated your local files with a ``git pull`` (or ``git
+checkout``), you still need to re-build LAMMPS if any source files have
 changed.  To do this, you should cd to the src directory and type:
 
 .. code-block:: bash
@@ -95,7 +94,7 @@ changed.  To do this, you should cd to the src directory and type:
    $ make package-update    # sync package files with src files
    $ make foo               # re-build for your machine (mpi, serial, etc)
 
-just as described on the :doc:`Install patch <Install_patch>` doc page,
+just as described on the :doc:`Apply patch <Install_patch>` page,
 after a patch has been installed.
 
 .. warning::

doc/src/Install_linux.rst

@@ -79,13 +79,13 @@ To get a copy of the current potentials files:
 which will download the potentials files to
 ``/usr/share/lammps-stable/potentials``.  The ``lmp_stable`` binary is
 hard-coded to look for potential files in this directory (it does not
-use the `LAMMPS_POTENTIALS` environment variable, as described
+use the ``LAMMPS_POTENTIALS`` environment variable, as described
 in :doc:`pair_coeff <pair_coeff>` command).
 
 The ``lmp_stable`` binary is built with the :ref:`KIM package <kim>` which
-results in the above command also installing the `kim-api` binaries when LAMMPS
+results in the above command also installing the ``kim-api`` binaries when LAMMPS
 is installed.  In order to use potentials from `openkim.org <openkim_>`_, you
-can install the `openkim-models` package
+can install the ``openkim-models`` package
 
 .. code-block:: bash
 

doc/src/Install_patch.rst

@@ -6,9 +6,12 @@ if you use git to track the LAMMPS development.  Instructions for
 how to stay current are on the
 :doc:`Download the LAMMPS source with git <Install_git>` page.
 
-If you prefer to download a tarball, as described on the :doc:`Install git <Install_tarball>` doc page, you can stay current by
+If you prefer to download a tarball, as described on the
+:doc:`tarball download <Install_tarball>` page, you can stay current by
 downloading "patch files" when new patch releases are made.  A link to
-a patch file is posted on the `bug and feature page <https://lammps.sandia.gov/bug.html>`_ of the LAMMPS website, along
+a patch file is posted on the
+`bug fixes and new feature page <https://lammps.sandia.gov/bug.html>`_
+of the LAMMPS website, along
 with a list of changed files and details about what is in the new patch
 release.  This page explains how to apply the patch file to your local
 LAMMPS directory.

doc/src/Install_tarball.rst

@@ -61,4 +61,4 @@ periodically.)
 The patch files are posted on the `bug and feature page <bug_>`_ of the
 website, along with a list of changed files and details about what is
 in the new patch release.  Instructions for applying a patch file are
-on the :doc:`Install patch <Install_patch>` doc page.
+on the :doc:`Install patch <Install_patch>` page.

doc/src/Install_windows.rst

@@ -12,14 +12,20 @@ Note that each installer package has a date in its name, which
 corresponds to the LAMMPS version of the same date.  Installers for
 current and older versions of LAMMPS are available.  32-bit and 64-bit
 installers are available, and each installer contains both a serial
-and parallel executable.  The installer site also explains how to
+and parallel executable.  The installer web site also explains how to
 install the Windows MPI package (MPICH2 from Argonne National Labs),
 needed to run in parallel.
 
-The LAMMPS binaries contain all optional packages included in the
-source distribution except: KIM, KOKKOS, USER-INTEL, and USER-QMMM.
+The LAMMPS binaries contain *all* :doc:`optional packages <Packages>`
+included in the source distribution except: KIM, KOKKOS, MSCG, PYTHON,
+USER-ADIOS, USER-H5MD, USER-NETCDF, USER-QMMM, USER-QUIP, and USER-VTK.
 The serial version also does not include the MPIIO and
-USER-LB packages.  GPU support is provided for OpenCL.
+USER-LB packages.  The GPU package is compiled for OpenCL with
+mixed precision kernels.
+
+The LAMMPS library is compiled as a shared library and the
+:doc:`LAMMPS Python module <Python_module>` is installed, so that
+it is possible to load LAMMPS into a Python interpreter.
 
 The installer site also has instructions on how to run LAMMPS under
 Windows, once it is installed, in both serial and parallel.
@@ -42,5 +48,3 @@ install multiple versions of LAMMPS (in different directories), but
 only the executable for the last-installed package will be found
 automatically, so this should only be done for debugging purposes.
 
-Thanks to Axel Kohlmeyer (Temple U, akohlmey at gmail.com) for setting
-up this Windows capability.

doc/src/Intro.rst

@@ -12,4 +12,5 @@ These pages provide a brief introduction to LAMMPS.
    Intro_nonfeatures
    Intro_opensource
    Intro_authors
+   Intro_citing
    Intro_website

doc/src/Intro_citing.rst

@@ -0,0 +1,52 @@
+Citing LAMMPS
+=============
+
+Core Algorithms
+^^^^^^^^^^^^^^^
+
+Since LAMMPS is a community project, there is not a single one
+publication or reference that describes **all** of LAMMPS.
+The canonical publication that describes the foundation, that is
+the basic spatial decomposition approach, the neighbor finding,
+and basic communications algorithms used in LAMMPS is:
+
+ `S. Plimpton, Fast Parallel Algorithms for Short-Range Molecular Dynamics, J Comp Phys, 117, 1-19 (1995). <http://www.sandia.gov/~sjplimp/papers/jcompphys95.pdf>`_
+
+So any project using LAMMPS (or a derivative application using LAMMPS as
+a simulation engine) should cite this paper. A new publication
+describing the developments and improvements of LAMMPS in the 25 years
+since then is currently in preparation.
+
+
+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:
+
+  `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>`_
+
+
+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.
+
+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
+<Commands_all>` or in the :doc:`Howto tutorials <Howto>`.