Merge pull request #2414 from akohlmey/next_lammps_version

Update version strings for next patch release

.gitattributes

@@ -0,0 +1,3 @@
+.gitattributes export-ignore
+.gitignore export-ignore
+.github export-ignore

.github/CODEOWNERS

@@ -114,11 +114,14 @@ 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
 tools/emacs/*         @HaoZeke
 tools/singularity/*   @akohlmey @rbberger
+tools/code_standard/* @rbberger
+tools/valgrind/*      @akohlmey
 
 # tests
 unittest/*            @akohlmey @rbberger
@@ -132,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**
 

.github/codecov.yml

@@ -0,0 +1,29 @@
+comment: false
+coverage:
+  notify:
+    slack:
+      default:
+        url: "secret:HWZbvgtc6OD7F3v3PfrK3/rzCJvScbh69Fi1CkLwuHK0+wIBIHVR+Q5i7q6F9Ln4OChbiRGtYAEUUsT8/jmBu4qDpIi8mx746codc0z/Z3aafLd24pBrCEPLvdCfIZxqPnw3TuUgGhwmMDZf0+thg8YNUr/MbOZ7Li2L6+ZbYuA="
+        threshold: 10%
+        only_pulls: false
+        branches:
+          - "master"
+        flags:
+          - "unit"
+        paths:
+          - "src"
+  status:
+    project:
+        default:
+            branches:
+              - "master"
+            paths:
+              - "src"
+            informational: true
+    patch:
+        default:
+            branches:
+              - "master"
+            paths:
+              - "src"
+            informational: true

.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

@@ -57,7 +57,6 @@ check_for_autogen_files(${LAMMPS_SOURCE_DIR})
 # compiler tests
 # these need ot be done early (before further tests).
 #####################################################################
-include(CheckCCompilerFlag)
 include(CheckIncludeFileCXX)
 
 # set required compiler flags and compiler/CPU arch specific optimizations
@@ -70,27 +69,10 @@ if(${CMAKE_CXX_COMPILER_ID} STREQUAL "Intel")
   endif()
 endif()
 
-if(${CMAKE_CXX_COMPILER_ID} STREQUAL "GNU")
-  set(CMAKE_TUNE_DEFAULT "-march=native")
-endif()
-
-if(${CMAKE_CXX_COMPILER_ID} STREQUAL "Clang")
-  set(CMAKE_TUNE_DEFAULT "-march=native")
-endif()
-
 # we require C++11 without extensions
 set(CMAKE_CXX_STANDARD 11)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
-set(CMAKE_CXX_EXTENSIONS OFF)
-
-# GNU compiler specific features for testing
-if (${CMAKE_CXX_COMPILER_ID} STREQUAL "GNU")
-  option(ENABLE_COVERAGE "Enable collecting code coverage data" OFF)
-  mark_as_advanced(ENABLE_COVERAGE)
-  if(ENABLE_COVERAGE)
-    set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} --coverage")
-  endif()
-endif()
+set(CMAKE_CXX_EXTENSIONS OFF CACHE BOOL "Use compiler extensions")
 
 ########################################################################
 # User input options                                                   #
@@ -108,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)
@@ -122,8 +105,8 @@ install(TARGETS lmp EXPORT LAMMPS_Targets DESTINATION ${CMAKE_INSTALL_BINDIR})
 option(CMAKE_VERBOSE_MAKEFILE "Generate verbose Makefiles" OFF)
 
 set(STANDARD_PACKAGES ASPHERE BODY CLASS2 COLLOID COMPRESS DIPOLE
-  GRANULAR KSPACE LATTE MANYBODY MC MESSAGE MISC MOLECULE PERI POEMS QEQ
-  REPLICA RIGID SHOCK SPIN SNAP SRD KIM PYTHON MSCG MPIIO VORONOI
+  GRANULAR KSPACE LATTE MANYBODY MC MESSAGE MISC MLIAP MOLECULE PERI POEMS
+  QEQ REPLICA RIGID SHOCK SPIN SNAP SRD KIM PYTHON MSCG MPIIO VORONOI
   USER-ATC USER-AWPMD USER-BOCS USER-CGDNA USER-MESODPD USER-CGSDK USER-COLVARS
   USER-DIFFRACTION USER-DPD USER-DRUDE USER-EFF USER-FEP USER-H5MD USER-LB
   USER-MANIFOLD USER-MEAMC USER-MESONT USER-MGPT USER-MISC USER-MOFFF USER-MOLFILE
@@ -175,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()
@@ -203,13 +186,14 @@ if(NOT ${LAMMPS_MEMALIGN} STREQUAL "0")
   target_compile_definitions(lammps PRIVATE -DLAMMPS_MEMALIGN=${LAMMPS_MEMALIGN})
 endif()
 
-option(LAMMPS_EXCEPTIONS "enable the use of C++ exceptions for error messages (useful for library interface)" OFF)
+option(LAMMPS_EXCEPTIONS "enable the use of C++ exceptions for error messages (useful for library interface)" ${ENABLE_TESTING})
 if(LAMMPS_EXCEPTIONS)
   target_compile_definitions(lammps PUBLIC -DLAMMPS_EXCEPTIONS)
 endif()
 
 # "hard" dependencies between packages resulting
 # in an error instead of skipping over files
+pkg_depends(MLIAP SNAP)
 pkg_depends(MPIIO MPI)
 pkg_depends(USER-ATC MANYBODY)
 pkg_depends(USER-LB MPI)
@@ -235,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)
@@ -248,6 +231,68 @@ if(BUILD_OMP)
   target_link_libraries(lammps PRIVATE OpenMP::OpenMP_CXX)
 endif()
 
+# Compiler specific features for testing
+if(${CMAKE_CXX_COMPILER_ID} STREQUAL "GNU")
+  option(ENABLE_COVERAGE "Enable collecting code coverage data" OFF)
+  mark_as_advanced(ENABLE_COVERAGE)
+  if(ENABLE_COVERAGE)
+    if(CMAKE_VERSION VERSION_LESS 3.13)
+      if(CMAKE_CXX_FLAGS)
+        set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} --coverage")
+      else()
+        set(CMAKE_CXX_FLAGS "${CMAKE_CXX_${CMAKE_BUILD_TYPE}_FLAGS} --coverage")
+      endif()
+    else()
+      target_compile_options(lammps PUBLIC --coverage)
+      target_link_options(lammps PUBLIC --coverage)
+    endif()
+  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)
+set_property(CACHE ENABLE_SANITIZER PROPERTY STRINGS ${ENABLE_SANITIZER_VALUES})
+validate_option(ENABLE_SANITIZER ENABLE_SANITIZER_VALUES)
+string(TOLOWER ${ENABLE_SANITIZER} ENABLE_SANITIZER)
+if(NOT ENABLE_SANITIZER STREQUAL "none")
+  if((${CMAKE_CXX_COMPILER_ID} STREQUAL "GNU") OR (${CMAKE_CXX_COMPILER_ID} STREQUAL "Clang"))
+    if(CMAKE_VERSION VERSION_LESS 3.13)
+      if(CMAKE_CXX_FLAGS)
+        set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fsanitize=${ENABLE_SANITIZER}")
+      else()
+        set(CMAKE_CXX_FLAGS "${CMAKE_CXX_${CMAKE_BUILD_TYPE}_FLAGS} -fsanitize=${ENABLE_SANITIZER}")
+      endif()
+    else()
+      target_compile_options(lammps PUBLIC -fsanitize=${ENABLE_SANITIZER})
+      target_link_options(lammps PUBLIC -fsanitize=${ENABLE_SANITIZER})
+    endif()
+  else()
+    message(WARNING "ENABLE_SANITIZER option not supported by ${CMAKE_CXX_COMPILER_ID} compilers. Ignoring.")
+    set(ENABLE_SANITIZER "none")
+  endif()
+endif()
+
 if(PKG_MSCG OR PKG_USER-ATC OR PKG_USER-AWPMD OR PKG_USER-QUIP OR PKG_LATTE)
   enable_language(C)
   find_package(LAPACK)
@@ -268,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)
@@ -300,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)
@@ -333,17 +379,10 @@ foreach(PKG_WITH_INCL KSPACE PYTHON VORONOI USER-COLVARS USER-MOLFILE USER-NETCD
   endif()
 endforeach()
 
-set(CMAKE_TUNE_FLAGS "${CMAKE_TUNE_DEFAULT}" CACHE STRING "Compiler specific optimization or instrumentation")
+set(CMAKE_TUNE_FLAGS "${CMAKE_TUNE_DEFAULT}" CACHE STRING "Compiler and machine specific optimization flags (compilation only)")
 separate_arguments(CMAKE_TUNE_FLAGS)
-include(CheckCXXCompilerFlag)
 foreach(_FLAG ${CMAKE_TUNE_FLAGS})
-  string(REGEX REPLACE "[=\"]" "" _FLAGX ${_FLAG})
-  check_cxx_compiler_flag("${_FLAG}" COMPILER_SUPPORTS${_FLAGX})
-  if(COMPILER_SUPPORTS${_FLAGX})
-    target_compile_options(lammps PRIVATE ${_FLAG})
-  else()
-    message(WARNING "${_FLAG} found in CMAKE_TUNE_FLAGS, but not supported by the compiler, skipping")
-  endif()
+  target_compile_options(lammps PRIVATE ${_FLAG})
 endforeach()
 ########################################################################
 # Basic system tests (standard libraries, headers, functions, types)   #
@@ -538,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()
@@ -574,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)
 
 ###############################################################################
@@ -699,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}
@@ -729,6 +740,12 @@ if (${_index} GREATER -1)
 endif()
 message(STATUS "<<< Linker flags: >>>")
 message(STATUS "Executable name:  ${LAMMPS_BINARY}")
+if(CMAKE_VERSION VERSION_GREATER_EQUAL 3.13)
+  get_target_property(OPTIONS lammps LINK_OPTIONS)
+  if(OPTIONS)
+    message(STATUS "Linker options:   ${OPTIONS}")
+  endif()
+endif()
 if(CMAKE_EXE_LINKER_FLAGS)
   message(STATUS "Executable linker flags: ${CMAKE_EXE_LINKER_FLAGS}")
 endif()
@@ -792,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
-    COMMAND ${DOCENV_BINARY_DIR}/pip install -r requirements.txt --upgrade
+    OUTPUT ${DOC_BUILD_DIR}/requirements.txt
+    DEPENDS docenv ${DOCENV_REQUIREMENTS_FILE}
+    COMMAND ${CMAKE_COMMAND} -E copy ${DOCENV_REQUIREMENTS_FILE} ${DOC_BUILD_DIR}/requirements.txt
+    COMMAND ${DOCENV_BINARY_DIR}/pip install --upgrade pip
     COMMAND ${DOCENV_BINARY_DIR}/pip install --upgrade ${LAMMPS_DOC_DIR}/utils/converters
+    COMMAND ${DOCENV_BINARY_DIR}/pip install --use-feature=2020-resolver -r ${DOC_BUILD_DIR}/requirements.txt --upgrade
   )
 
   # 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/GTest.cmake

@@ -7,9 +7,11 @@ else()
 endif()
 
 include(ExternalProject)
+set(GTEST_URL "https://github.com/google/googletest/archive/release-1.10.0.tar.gz" CACHE STRING "URL for GTest tarball")
+mark_as_advanced(GTEST_URL)
 ExternalProject_Add(googletest
-                    GIT_REPOSITORY  https://github.com/google/googletest.git
-                    GIT_TAG         release-1.10.0
+                    URL ${GTEST_URL}
+                    URL_MD5         ecd1fa65e7de707cd5c00bdac56022cd
                     SOURCE_DIR      "${CMAKE_BINARY_DIR}/gtest-src"
                     BINARY_DIR      "${CMAKE_BINARY_DIR}/gtest-build"
                     CMAKE_ARGS      ${CMAKE_REQUEST_PIC} ${CMAKE_EXTRA_GTEST_OPTS}
@@ -52,26 +54,26 @@ add_library(GTest::GTest UNKNOWN IMPORTED)
 set_target_properties(GTest::GTest PROPERTIES
         IMPORTED_LOCATION ${GTEST_LIBRARY_PATH}
         INTERFACE_INCLUDE_DIRECTORIES ${GTEST_INCLUDE_DIR}
-        IMPORTED_LINK_INTERFACE_LIBRARIES ${CMAKE_THREAD_LIBS_INIT})
+        INTERFACE_LINK_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}")
 add_dependencies(GTest::GTest googletest)
 
 add_library(GTest::GMock UNKNOWN IMPORTED)
 set_target_properties(GTest::GMock PROPERTIES
         IMPORTED_LOCATION ${GMOCK_LIBRARY_PATH}
         INTERFACE_INCLUDE_DIRECTORIES ${GMOCK_INCLUDE_DIR}
-        IMPORTED_LINK_INTERFACE_LIBRARIES ${CMAKE_THREAD_LIBS_INIT})
+        INTERFACE_LINK_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}")
 add_dependencies(GTest::GMock googletest)
 
 add_library(GTest::GTestMain UNKNOWN IMPORTED)
 set_target_properties(GTest::GTestMain PROPERTIES
         IMPORTED_LOCATION ${GTEST_MAIN_LIBRARY_PATH}
         INTERFACE_INCLUDE_DIRECTORIES ${GTEST_INCLUDE_DIR}
-        IMPORTED_LINK_INTERFACE_LIBRARIES ${CMAKE_THREAD_LIBS_INIT})
+        INTERFACE_LINK_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}")
 add_dependencies(GTest::GTestMain googletest)
 
 add_library(GTest::GMockMain UNKNOWN IMPORTED)
 set_target_properties(GTest::GMockMain PROPERTIES
         IMPORTED_LOCATION ${GMOCK_MAIN_LIBRARY_PATH}
         INTERFACE_INCLUDE_DIRECTORIES ${GMOCK_INCLUDE_DIR}
-        IMPORTED_LINK_INTERFACE_LIBRARIES ${CMAKE_THREAD_LIBS_INIT})
+        INTERFACE_LINK_LIBRARIES "${CMAKE_THREAD_LIBS_INIT}")
 add_dependencies(GTest::GMockMain googletest)

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

@@ -64,30 +64,41 @@ if(GPU_API STREQUAL "CUDA")
 
   # build arch/gencode commands for nvcc based on CUDA toolkit version and use choice
   # --arch translates directly instead of JIT, so this should be for the preferred or most common architecture
-  set(GPU_CUDA_GENCODE "-arch=${GPU_ARCH} ")
+  set(GPU_CUDA_GENCODE "-arch=${GPU_ARCH}")
   # Fermi (GPU Arch 2.x) is supported by CUDA 3.2 to CUDA 8.0
-  if((CUDA_VERSION VERSION_GREATER "3.1") AND (CUDA_VERSION VERSION_LESS "9.0"))
-    string(APPEND GPU_CUDA_GENCODE "-gencode arch=compute_20,code=[sm_20,compute_20] ")
+  if((CUDA_VERSION VERSION_GREATER_EQUAL "3.2") AND (CUDA_VERSION VERSION_LESS "9.0"))
+    string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_20,code=[sm_20,compute_20] ")
   endif()
-  # Kepler (GPU Arch 3.x) is supported by CUDA 5 and later
-  if(CUDA_VERSION VERSION_GREATER "4.9")
-    string(APPEND GPU_CUDA_GENCODE "-gencode arch=compute_30,code=[sm_30,compute_30] -gencode arch=compute_35,code=[sm_35,compute_35] ")
+  # Kepler (GPU Arch 3.0) is supported by CUDA 5 to CUDA 10.2
+  if((CUDA_VERSION VERSION_GREATER_EQUAL "5.0") AND (CUDA_VERSION VERSION_LESS "11.0"))
+    string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_30,code=[sm_30,compute_30] ")
+  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_35,code=[sm_35,compute_35]")
   endif()
   # Maxwell (GPU Arch 5.x) is supported by CUDA 6 and later
-  if(CUDA_VERSION VERSION_GREATER "5.9")
-    string(APPEND GPU_CUDA_GENCODE "-gencode arch=compute_50,code=[sm_50,compute_50] -gencode arch=compute_52,code=[sm_52,compute_52] ")
+  if(CUDA_VERSION VERSION_GREATER_EQUAL "6.0")
+    string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_50,code=[sm_50,compute_50] -gencode arch=compute_52,code=[sm_52,compute_52]")
   endif()
   # Pascal (GPU Arch 6.x) is supported by CUDA 8 and later
-  if(CUDA_VERSION VERSION_GREATER "7.9")
-    string(APPEND GPU_CUDA_GENCODE "-gencode arch=compute_60,code=[sm_60,compute_60] -gencode arch=compute_61,code=[sm_61,compute_61] ")
+  if(CUDA_VERSION VERSION_GREATER_EQUAL "8.0")
+    string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_60,code=[sm_60,compute_60] -gencode arch=compute_61,code=[sm_61,compute_61]")
   endif()
   # Volta (GPU Arch 7.0) is supported by CUDA 9 and later
-  if(CUDA_VERSION VERSION_GREATER "8.9")
-    string(APPEND GPU_CUDA_GENCODE "-gencode arch=compute_70,code=[sm_70,compute_70] ")
+  if(CUDA_VERSION VERSION_GREATER_EQUAL "9.0")
+    string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_70,code=[sm_70,compute_70]")
   endif()
   # Turing (GPU Arch 7.5) is supported by CUDA 10 and later
-  if(CUDA_VERSION VERSION_GREATER "9.9")
-    string(APPEND GPU_CUDA_GENCODE "-gencode arch=compute_75,code=[sm_75,compute_75] ")
+  if(CUDA_VERSION VERSION_GREATER_EQUAL "10.0")
+    string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_75,code=[sm_75,compute_75]")
+  endif()
+  # Ampere (GPU Arch 8.0) is supported by CUDA 11 and later
+  if(CUDA_VERSION VERSION_GREATER_EQUAL "11.0")
+    string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_80,code=[sm_80,compute_80]")
+  endif()
+  if(CUDA_VERSION VERSION_GREATER_EQUAL "12.0")
+    message(WARNING "Unsupported CUDA version. Use at your own risk.")
   endif()
 
   cuda_compile_fatbin(GPU_GEN_OBJS ${GPU_LIB_CU} OPTIONS ${CUDA_REQUEST_PIC}
@@ -226,30 +237,41 @@ elseif(GPU_API STREQUAL "HIP")
 
     # build arch/gencode commands for nvcc based on CUDA toolkit version and use choice
     # --arch translates directly instead of JIT, so this should be for the preferred or most common architecture
-    set(HIP_CUDA_GENCODE "-arch=${HIP_ARCH} ")
+    set(HIP_CUDA_GENCODE "-arch=${HIP_ARCH}")
     # Fermi (GPU Arch 2.x) is supported by CUDA 3.2 to CUDA 8.0
-    if((CUDA_VERSION VERSION_GREATER "3.1") AND (CUDA_VERSION VERSION_LESS "9.0"))
-      string(APPEND HIP_CUDA_GENCODE "-gencode arch=compute_20,code=[sm_20,compute_20] ")
+    if((CUDA_VERSION VERSION_GREATER_EQUAL "3.2") AND (CUDA_VERSION VERSION_LESS "9.0"))
+      string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_20,code=[sm_20,compute_20]")
     endif()
-    # Kepler (GPU Arch 3.x) is supported by CUDA 5 and later
-    if(CUDA_VERSION VERSION_GREATER "4.9")
-      string(APPEND HIP_CUDA_GENCODE "-gencode arch=compute_30,code=[sm_30,compute_30] -gencode arch=compute_35,code=[sm_35,compute_35] ")
+    # Kepler (GPU Arch 3.0) is supported by CUDA 5 to CUDA 10.2
+    if((CUDA_VERSION VERSION_GREATER_EQUAL "5.0") AND (CUDA_VERSION VERSION_LESS "11.0"))
+      string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_30,code=[sm_30,compute_30]")
+    endif()
+    # Kepler (GPU Arch 3.5) is supported by CUDA 5 to CUDA 11.0
+    if((CUDA_VERSION VERSION_GREATER_EQUAL "5.0") AND (CUDA_VERSION VERSION_LESS "12.0"))
+      string(APPEND HIP_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 "5.9")
-      string(APPEND HIP_CUDA_GENCODE "-gencode arch=compute_50,code=[sm_50,compute_50] -gencode arch=compute_52,code=[sm_52,compute_52] ")
+    if(CUDA_VERSION VERSION_GREATER_EQUAL "6.0")
+      string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_50,code=[sm_50,compute_50] -gencode arch=compute_52,code=[sm_52,compute_52]")
     endif()
     # Pascal (GPU Arch 6.x) is supported by CUDA 8 and later
-    if(CUDA_VERSION VERSION_GREATER "7.9")
-      string(APPEND HIP_CUDA_GENCODE "-gencode arch=compute_60,code=[sm_60,compute_60] -gencode arch=compute_61,code=[sm_61,compute_61] ")
+    if(CUDA_VERSION VERSION_GREATER_EQUAL "8.0")
+      string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_60,code=[sm_60,compute_60] -gencode arch=compute_61,code=[sm_61,compute_61]")
     endif()
     # Volta (GPU Arch 7.0) is supported by CUDA 9 and later
-    if(CUDA_VERSION VERSION_GREATER "8.9")
-      string(APPEND HIP_CUDA_GENCODE "-gencode arch=compute_70,code=[sm_70,compute_70] ")
+    if(CUDA_VERSION VERSION_GREATER_EQUAL "9.0")
+      string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_70,code=[sm_70,compute_70]")
     endif()
     # Turing (GPU Arch 7.5) is supported by CUDA 10 and later
-    if(CUDA_VERSION VERSION_GREATER "9.9")
-      string(APPEND HIP_CUDA_GENCODE "-gencode arch=compute_75,code=[sm_75,compute_75] ")
+    if(CUDA_VERSION VERSION_GREATER_EQUAL "10.0")
+      string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_75,code=[sm_75,compute_75]")
+    endif()
+    # Ampere (GPU Arch 8.0) is supported by CUDA 11 and later
+    if(CUDA_VERSION VERSION_GREATER_EQUAL "11.0")
+      string(APPEND HIP_CUDA_GENCODE " -gencode arch=compute_80,code=[sm_80,compute_80]")
+    endif()
+    if(CUDA_VERSION VERSION_GREATER_EQUAL "12.0")
+      message(WARNING "Unsupported CUDA version. Use at your own risk.")
     endif()
   endif()
 
@@ -268,10 +290,17 @@ elseif(GPU_API STREQUAL "HIP")
     if(HIP_PLATFORM STREQUAL "hcc")
         configure_file(${CU_FILE} ${CU_CPP_FILE} COPYONLY)
 
-        add_custom_command(OUTPUT ${CUBIN_FILE}
-          VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --genco -t="${HIP_ARCH}" -f=\"-O3 -ffast-math -DUSE_HIP -D_${GPU_PREC_SETTING} -I${LAMMPS_LIB_SOURCE_DIR}/gpu\" -o ${CUBIN_FILE} ${CU_CPP_FILE}
-          DEPENDS ${CU_CPP_FILE}
-          COMMENT "Generating ${CU_NAME}.cubin")
+        if(HIP_COMPILER STREQUAL "clang")
+          add_custom_command(OUTPUT ${CUBIN_FILE}
+            VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --genco --offload-arch=${HIP_ARCH} -O3 -ffast-math -DUSE_HIP -D_${GPU_PREC_SETTING} -I${LAMMPS_LIB_SOURCE_DIR}/gpu -o ${CUBIN_FILE} ${CU_CPP_FILE}
+            DEPENDS ${CU_CPP_FILE}
+            COMMENT "Generating ${CU_NAME}.cubin")
+        else()
+          add_custom_command(OUTPUT ${CUBIN_FILE}
+            VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --genco -t="${HIP_ARCH}" -f=\"-O3 -ffast-math -DUSE_HIP -D_${GPU_PREC_SETTING} -I${LAMMPS_LIB_SOURCE_DIR}/gpu\" -o ${CUBIN_FILE} ${CU_CPP_FILE}
+            DEPENDS ${CU_CPP_FILE}
+            COMMENT "Generating ${CU_NAME}.cubin")
+        endif()
     elseif(HIP_PLATFORM STREQUAL "nvcc")
         add_custom_command(OUTPUT ${CUBIN_FILE}
           VERBATIM COMMAND ${HIP_HIPCC_EXECUTABLE} --fatbin --use_fast_math -DUSE_HIP -D_${GPU_PREC_SETTING} ${HIP_CUDA_GENCODE} -I${LAMMPS_LIB_SOURCE_DIR}/gpu -o ${CUBIN_FILE} ${CU_FILE}
@@ -280,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-INTEL.cmake

@@ -77,7 +77,7 @@ else()
     foreach(_FLAG -O2 -fp-model fast=2 -no-prec-div -qoverride-limits -qopt-zmm-usage=high -qno-offload -fno-alias -ansi-alias -restrict)
       check_cxx_compiler_flag("${_FLAG}" COMPILER_SUPPORTS${_FLAG})
       if(COMPILER_SUPPORTS${_FLAG})
-	  target_compile_options(lammps PRIVATE ${_FLAG})
+          target_compile_options(lammps PRIVATE ${_FLAG})
       endif()
     endforeach()
   endif()

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/Packages/USER-SCAFACOS.cmake

@@ -14,40 +14,23 @@ endif()
 option(DOWNLOAD_SCAFACOS "Download ScaFaCoS library instead of using an already installed one" ${DOWNLOAD_SCAFACOS_DEFAULT})
 if(DOWNLOAD_SCAFACOS)
   message(STATUS "ScaFaCoS download requested - we will build our own")
-  # create variables to pass our compiler flags along to the subsystem compile
-  # need to apply -fallow-argument-mismatch, if the fortran compiler supports it
-  include(CheckFortranCompilerFlag)
-  check_fortran_compiler_flag("-fallow-argument-mismatch" GNUFortran_ARGUMENT_MISMATCH_FLAG)
-  if(GNUFortran_ARGUMENT_MISMATCH_FLAG)
-    set(APPEND_Fortran_FLAG "-fallow-argument-mismatch")
-  endif()
-  if(CMAKE_Fortran_FLAGS)
-    set(SCAFACOS_Fortran_FLAGS "${CMAKE_Fortran_FLAGS} ${APPEND_Fortran_FLAG}")
-  else()
-    set(SCAFACOS_Fortran_FLAGS "${CMAKE_Fortran_${CMAKE_BUILD_TYPE}_FLAGS} ${APPEND_Fortran_FLAG}")
-  endif()
-  if(CMAKE_CXX_FLAGS)
-      set(SCAFACOS_CXX_FLAGS "${CMAKE_CXX_FLAGS}")
-    else()
-      set(SCAFACOS_CXX_FLAGS "${CMAKE_CXX_${CMAKE_BUILD_TYPE}_FLAGS}")
-  endif()
-  if(CMAKE_C_FLAGS)
-      set(SCAFACOS_C_FLAGS "${CMAKE_C_FLAGS}")
-    else()
-      set(SCAFACOS_C_FLAGS "${CMAKE_C_${CMAKE_BUILD_TYPE}_FLAGS}")
-  endif()
+
+  # version 1.0.1 needs a patch to compile and linke cleanly with GCC 10 and later.
+  file(DOWNLOAD https://download.lammps.org/thirdparty/scafacos-1.0.1-fix.diff ${CMAKE_CURRENT_BINARY_DIR}/scafacos-1.0.1.fix.diff
+          EXPECTED_HASH MD5=4baa1333bb28fcce102d505e1992d032)
 
   include(ExternalProject)
   ExternalProject_Add(scafacos_build
     URL https://github.com/scafacos/scafacos/releases/download/v1.0.1/scafacos-1.0.1.tar.gz
     URL_MD5 bd46d74e3296bd8a444d731bb10c1738
+    PATCH_COMMAND patch -p1 < ${CMAKE_CURRENT_BINARY_DIR}/scafacos-1.0.1.fix.diff
     CONFIGURE_COMMAND <SOURCE_DIR>/configure --prefix=<INSTALL_DIR> --disable-doc
                                              --enable-fcs-solvers=fmm,p2nfft,direct,ewald,p3m
                                              --with-internal-fftw --with-internal-pfft
                                              --with-internal-pnfft ${CONFIGURE_REQUEST_PIC}
-                                             FC=${CMAKE_MPI_Fortran_COMPILER} FCFLAGS=${SCAFACOS_Fortran_FLAGS}
-                                             CXX=${CMAKE_MPI_CXX_COMPILER} CXXFLAGS=${SCAFACOS_CXX_FLAGS}
-                                             CC=${CMAKE_MPI_C_COMPILER} CFLAGS=${SCAFACOS_C_FLAGS}
+                                             FC=${CMAKE_MPI_Fortran_COMPILER}
+                                             CXX=${CMAKE_MPI_CXX_COMPILER}
+                                             CC=${CMAKE_MPI_C_COMPILER}
                                              F77=
     BUILD_BYPRODUCTS
       <INSTALL_DIR>/lib/libfcs.a

cmake/Modules/Packages/USER-SMD.cmake

@@ -9,8 +9,8 @@ if(DOWNLOAD_EIGEN3)
   message(STATUS "Eigen3 download requested - we will build our own")
   include(ExternalProject)
   ExternalProject_Add(Eigen3_build
-    URL https://bitbucket.org/eigen/eigen/get/3.3.7.tar.gz
-    URL_MD5 f2a417d083fe8ca4b8ed2bc613d20f07
+    URL https://gitlab.com/libeigen/eigen/-/archive/3.3.7/eigen-3.3.7.tar.gz
+    URL_MD5 9e30f67e8531477de4117506fe44669b
     CONFIGURE_COMMAND "" BUILD_COMMAND "" INSTALL_COMMAND ""
   )
   ExternalProject_get_property(Eigen3_build SOURCE_DIR)

cmake/Modules/Testing.cmake

@@ -3,6 +3,51 @@
 ###############################################################################
 option(ENABLE_TESTING "Enable testing" OFF)
 if(ENABLE_TESTING)
+  find_program(VALGRIND_BINARY NAMES valgrind)
+  # generate custom suppression file
+  file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/lammps.supp "\n")
+  file(GLOB VALGRIND_SUPPRESSION_FILES ${LAMMPS_TOOLS_DIR}/valgrind/[^.]*.supp)
+  foreach(SUPP ${VALGRIND_SUPPRESSION_FILES})
+    file(READ ${SUPP} SUPPRESSIONS)
+    file(APPEND ${CMAKE_CURRENT_BINARY_DIR}/lammps.supp "${SUPPRESSIONS}")
+  endforeach()
+  set(VALGRIND_DEFAULT_OPTIONS "--leak-check=full --show-leak-kinds=all --track-origins=yes --suppressions=${CMAKE_BINARY_DIR}/lammps.supp")
+
+  set(MEMORYCHECK_COMMAND "${VALGRIND_BINARY}" CACHE FILEPATH "Memory Check Command")
+  set(MEMORYCHECK_COMMAND_OPTIONS "${VALGRIND_DEFAULT_OPTIONS}" CACHE STRING "Memory Check Command Options")
+
+  # check if a faster linker is available.
+  # only verified with GNU and Clang compilers and new CMake
+  if(CMAKE_VERSION VERSION_GREATER_EQUAL 3.13)
+    if((${CMAKE_CXX_COMPILER_ID} STREQUAL "GNU")
+        OR (${CMAKE_CXX_COMPILER_ID} STREQUAL "Clang"))
+      include(CheckCXXCompilerFlag)
+      set(CMAKE_CUSTOM_LINKER_DEFAULT default)
+      check_cxx_compiler_flag(-fuse-ld=lld HAVE_LLD_LINKER_FLAG)
+      check_cxx_compiler_flag(-fuse-ld=gold HAVE_GOLD_LINKER_FLAG)
+      check_cxx_compiler_flag(-fuse-ld=bfd HAVE_BFD_LINKER_FLAG)
+      find_program(HAVE_LLD_LINKER_BIN lld ld.lld)
+      find_program(HAVE_GOLD_LINKER_BIN ld.gold)
+      find_program(HAVE_BFD_LINKER_BIN ld.bfd)
+      if(HAVE_LLD_LINKER_FLAG AND HAVE_LLD_LINKER_BIN)
+        set(CMAKE_CUSTOM_LINKER_DEFAULT lld)
+      elseif(HAVE_GOLD_LINKER_FLAG AND HAVE_GOLD_LINKER_BIN)
+        set(CMAKE_CUSTOM_LINKER_DEFAULT gold)
+      elseif(HAVE_BFD_LINKER_FLAG AND HAVE_BFD_LINKER_BIN)
+        set(CMAKE_CUSTOM_LINKER_DEFAULT bfd)
+      endif()
+      set(CMAKE_CUSTOM_LINKER_VALUES lld gold bfd default)
+      set(CMAKE_CUSTOM_LINKER ${CMAKE_CUSTOM_LINKER_DEFAULT} CACHE STRING "Choose a custom linker for faster linking (lld, gold, bfd, default)")
+      validate_option(CMAKE_CUSTOM_LINKER CMAKE_CUSTOM_LINKER_VALUES)
+      mark_as_advanced(CMAKE_CUSTOM_LINKER)
+      if(NOT "${CMAKE_CUSTOM_LINKER}" STREQUAL "default")
+        target_link_options(lammps PUBLIC -fuse-ld=${CMAKE_CUSTOM_LINKER})
+      endif()
+    endif()
+  endif()
+
+  include(CTest)
+
   enable_testing()
   get_filename_component(LAMMPS_UNITTEST_DIR ${LAMMPS_SOURCE_DIR}/../unittest ABSOLUTE)
   get_filename_component(LAMMPS_UNITTEST_BIN ${CMAKE_BINARY_DIR}/unittest ABSOLUTE)

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)
 

cmake/presets/mingw-cross.cmake

@@ -1,6 +1,6 @@
 set(WIN_PACKAGES ASPHERE BODY CLASS2 COLLOID COMPRESS CORESHELL DIPOLE GPU
-                 GRANULAR KSPACE LATTE MANYBODY MC MISC MOLECULE OPT PERI
-                 POEMS QEQ REPLICA RIGID SHOCK SNAP SPIN SRD VORONOI
+                 GRANULAR KSPACE LATTE MANYBODY MC MISC MLIAP MOLECULE OPT
+                 PERI POEMS QEQ REPLICA RIGID SHOCK SNAP SPIN SRD VORONOI
                  USER-ATC USER-AWPMD USER-BOCS USER-CGDNA USER-CGSDK
                  USER-COLVARS USER-DIFFRACTION USER-DPD USER-DRUDE USER-EFF
                  USER-FEP USER-INTEL USER-MANIFOLD USER-MEAMC USER-MESODPD

cmake/presets/most.cmake

@@ -2,8 +2,8 @@
 # external libraries. Compared to all_on.cmake some more unusual packages
 # are removed. The resulting binary should be able to run most inputs.
 
-set(ALL_PACKAGES ASPHERE BODY CLASS2 COLLOID COMPRESS CORESHELL
-        DIPOLE GRANULAR KSPACE MANYBODY MC MISC MOLECULE OPT PERI
+set(ALL_PACKAGES ASPHERE BODY CLASS2 COLLOID COMPRESS CORESHELL DIPOLE
+        GRANULAR KSPACE MANYBODY MC MISC MLIAP MOLECULE OPT PERI
         POEMS PYTHON QEQ REPLICA RIGID SHOCK SNAP SPIN SRD VORONOI
         USER-BOCS USER-CGDNA USER-CGSDK USER-COLVARS USER-DIFFRACTION
         USER-DPD USER-DRUDE USER-EFF USER-FEP USER-MEAMC USER-MESODPD

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:' | 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,23 +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 Sphinx; \
-		pip install sphinxcontrib-spelling ;\
-		pip install breathe; \
+		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

@@ -25,10 +25,10 @@ In the interest of consistency, ONLY ONE of the core LAMMPS developers
 should doing the merging itself.  This is currently
 [@akohlmey](https://github.com/akohlmey) (Axel Kohlmeyer).
 If this assignment needs to be changed, it shall be done right after a
-stable release.  If the currently assigned developer cannot merge outstanding pull 
-requests in a timely manner, or in other extenuating circumstances, 
+stable release.  If the currently assigned developer cannot merge outstanding pull
+requests in a timely manner, or in other extenuating circumstances,
 other core LAMMPS developers with merge rights can merge pull requests,
-when necessary. 
+when necessary.
 
 ## Pull Requests
 
@@ -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
 
@@ -65,7 +65,7 @@ Header files will typically contain the definition of a (single) class.
 These header files should have as few include statements as possible.
 This is particularly important for classes that implement a "style" and
 thus use a macro of the kind `SomeStyle(some/name,SomeName)`. These will
-all be included in the auto-generated `"some_style.h"` files which 
+all be included in the auto-generated `"some_style.h"` files which
 results in a high potential for direct or indirect symbol name clashes.
 
 In the ideal case, the header would only include one file defining the
@@ -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 "15 June 2020" "2020-06-15"
+.TH LAMMPS "9 October 2020" "2020-10-09"
 .SH NAME
 .B LAMMPS
 \- Molecular Dynamics Simulator.

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,136 +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
-variable 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.  More on that below, but you can 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 these are initialized to some compiler specific flags, to
-optimize the LAMMPS executable with optimizations and instructions
-available on the host where LAMMPS is compiled. For example, for Intel
-compilers this would be ``-xHost`` and for GNU compilers this would be
-``-march=native``. To turn these flags off, do ``-D CMAKE_TUNE_FLAGS=``.
+      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
 ---------------------------------------
@@ -326,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
@@ -419,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
@@ -446,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
@@ -515,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
 
 ----------
 
@@ -550,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

@@ -8,8 +8,8 @@ useful during development, testing or debugging.
 
 .. _compilation:
 
-Verify compilation flags
-------------------------
+Monitor compilation flags
+-------------------------
 
 Sometimes it is necessary to verify the complete sequence of compilation flags
 generated by the CMake build. To enable a more verbose output during
@@ -19,7 +19,8 @@ compilation you can use the following option.
 
    -D CMAKE_VERBOSE_MAKEFILE=value    # value = no (default) or yes
 
-Another way of doing this without reconfiguration is calling make with variable VERBOSE set to 1:
+Another way of doing this without reconfiguration is calling make with
+variable VERBOSE set to 1:
 
 .. code-block:: bash
 
@@ -27,31 +28,67 @@ Another way of doing this without reconfiguration is calling make with variable
 
 ----------
 
+.. _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
 ---------------------------------------------------------
 
 Compilers such as GCC and Clang support generating instrumented binaries
-which use different sanitizer libraries to detect problems in code
+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 small
-performance hit (much less than using tools like `Valgrind
-<https://valgrind.org>`_).  The to enable these features additional
-compiler flags need to be added to the compilation and linking stages.
-This is most easily done through setting the ``CMAKE_TUNE_FLAGS``
-variable during configuration. Examples:
+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).  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:
 
 .. code-block:: bash
 
-   -D CMAKE_TUNE_FLAGS=-fsanitize=address    # enable address sanitizer / memory leak checker
-   -D CMAKE_TUNE_FLAGS=-fsanitize=undefined  # enable undefined behavior sanitizer
-   -D CMAKE_TUNE_FLAGS=-fsanitize=thread     # enable thread sanitizer
+   -D ENABLE_SANITIZER=none       # no sanitizer active (default)
+   -D ENABLE_SANITIZER=address    # enable address sanitizer / memory leak checker
+   -D ENABLE_SANITIZER=leak       # enable memory leak checker (only)
+   -D ENABLE_SANITIZER=undefined  # enable undefined behavior sanitizer
+   -D ENABLE_SANITIZER=thread     # enable thread sanitizer
 
 ----------
 
@@ -74,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.
@@ -86,19 +123,21 @@ The output of this command will be looking something like this::
    [...]$ ctest
    Test project /home/akohlmey/compile/lammps/build-testing
          Start  1: MolPairStyle:hybrid-overlay
-    1/26 Test  #1: MolPairStyle:hybrid-overlay .........   Passed    0.02 sec
+   1/109 Test  #1: MolPairStyle:hybrid-overlay .........   Passed    0.02 sec
          Start  2: MolPairStyle:hybrid
-    2/26 Test  #2: MolPairStyle:hybrid .................   Passed    0.01 sec
+   2/109 Test  #2: MolPairStyle:hybrid .................   Passed    0.01 sec
          Start  3: MolPairStyle:lj_class2
     [...]
-         Start 25: AngleStyle:harmonic
-   25/26 Test #25: AngleStyle:harmonic .................   Passed    0.01 sec
-         Start 26: AngleStyle:zero
-   26/26 Test #26: AngleStyle:zero .....................   Passed    0.01 sec
+         Start 107: PotentialFileReader
+ 107/109 Test #107: PotentialFileReader ................   Passed    0.04 sec
+         Start 108: EIMPotentialFileReader
+ 108/109 Test #108: EIMPotentialFileReader .............   Passed    0.03 sec
+         Start 109: TestSimpleCommands
+ 109/109 Test #109: TestSimpleCommands .................   Passed    0.02 sec
 
    100% tests passed, 0 tests failed out of 26
 
-   Total Test time (real) =   0.27 sec
+   Total Test time (real) =  25.57 sec
 
 
 The ``ctest`` command has many options, the most important ones are:
@@ -117,6 +156,8 @@ The ``ctest`` command has many options, the most important ones are:
      - exclude subset of tests matching the regular expression <regex>
    * - -N
      - dry-run: display list of tests without running them
+   * - -T memcheck
+     - run tests with valgrind memory checker (if available)
 
 In its full implementation, the unit test framework will consist of multiple
 kinds of tests implemented in different programming languages (C++, C, Python,
@@ -152,8 +193,8 @@ A test run is then a a collection multiple individual test runs each
 with many comparisons to reference results based on template input
 files, individual command settings, relative error margins, and
 reference data stored in a YAML format file with ``.yaml``
-suffix. Currently the programs ``pair_style``, ``bond_style``, and
-``angle_style`` are implemented.  They will compare forces, energies and
+suffix. Currently the programs ``test_pair_style``, ``test_bond_style``, and
+``test_angle_style`` are implemented.  They will compare forces, energies and
 (global) stress for all atoms after a ``run 0`` calculation and after a
 few steps of MD with :doc:`fix nve <fix_nve>`, each in multiple variants
 with different settings and also for multiple accelerated styles. If a
@@ -165,7 +206,7 @@ Below is an example command and output:
 
 .. parsed-literal::
 
-   [tests]$ pair_style mol-pair-lj_cut.yaml
+   [tests]$ test_pair_style mol-pair-lj_cut.yaml
    [==========] Running 6 tests from 1 test suite.
    [----------] Global test environment set-up.
    [----------] 6 tests from PairStyle
@@ -193,8 +234,8 @@ In this particular case, 5 out of 6 sets of tests were conducted, the
 tests for the ``lj/cut/opt`` pair style was skipped, since the tests
 executable did not include it.  To learn what individual tests are performed,
 you (currently) need to read the source code.  You can use code coverage
-recording (see next section) to confirm how well the tests cover the individual
-source files.
+recording (see next section) to confirm how well the tests cover the code
+paths in the individual source files.
 
 The force style test programs have a common set of options:
 
@@ -211,6 +252,14 @@ The force style test programs have a common set of options:
    * - -v
      - verbose output: also print the executed LAMMPS commands
 
+The ``ctest`` tool has no mechanism to directly pass flags to the individual
+test programs, but a workaround has been implemented where these flags can be
+set in an environment variable ``TEST_ARGS``. Example:
+
+.. code-block:: bash
+
+   env TEST_ARGS=-s ctest -V -R BondStyle
+
 To add a test for a style that is not yet covered, it is usually best
 to copy a YAML file for a similar style to a new file, edit the details
 of the style (how to call it, how to set its coefficients) and then
@@ -244,6 +293,81 @@ and working.
      of mis-compiled code (or an undesired large loss of precision due
      to significant reordering of operations and thus less error cancellation).
 
+Unit tests for timestepping related fixes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A substantial subset of :doc:`fix styles <fix>` are invoked regularly
+during MD timestepping and manipulate per-atom properties like
+positions, velocities, and forces.  For those fix styles, testing can be
+done in a very similar fashion as for force fields and thus there is a
+test program `test_fix_timestep` that shares a lot of code, properties,
+and command line flags with the force field style testers described in
+the previous section.
+
+This tester will set up a small molecular system run with verlet run
+style for 4 MD steps, then write a binary restart and continue for
+another 4 MD steps. At this point coordinates and velocities are
+recorded and compared to reference data. Then the system is cleared,
+restarted and running the second 4 MD steps again and the data is
+compared to the same reference. That is followed by another restart
+after which per atom type masses are replaced with per-atom masses and
+the second 4 MD steps are repeated again and compared to the same
+reference.  Also global scalar and vector data of the fix is recorded
+and compared.  If the fix is a thermostat and thus the internal property
+``t_target`` can be extracted, then this is compared to the reference
+data.  The tests are repeated with the respa run style.
+
+If the fix has a multi-threaded version in the USER-OMP package, then
+the entire set of tests is repeated for that version as well.
+
+For this to work, some additional conditions have to be met by the
+YAML format test inputs.
+
+- The fix to be tested (and only this fix), should be listed in the
+  ``prerequisites:`` section
+- The fix to be tested must be specified in the ``post_commands:``
+  section with the fix-ID ``test``.  This section may contain other
+  commands and other fixes (e.g. an instance of fix nve for testing
+  a thermostat or force manipulation fix)
+- For fixes that can tally contributions to the global virial, the
+  line ``fix_modify test virial yes`` should be included in the
+  ``post_commands:`` section of the test input.
+- For thermostat fixes the target temperature should be ramped from
+  an arbitrary value (e.g. 50K) to a pre-defined target temperature
+  entered as ``${t_target}``.
+- For fixes that have thermostatting support included, but do not
+  have it enabled in the input (e.g. fix rigid with default settings),
+  the ``post_commands:`` section should contain the line
+  ``variable t_target delete`` to disable the target temperature ramp
+  check to avoid false positives.
+
+Use custom linker for faster link times when ENABLE_TESTING is active
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When compiling LAMMPS with enabled tests, most test executables will
+need to be linked against the LAMMPS library.  Since this can be a very
+large library with many C++ objects when many packages are enabled, link
+times can become very long on machines that use the GNU BFD linker (e.g.
+Linux systems).  Alternatives like the ``lld`` linker of the LLVM project
+or the ``gold`` linker available with GNU binutils can speed up this step
+substantially. CMake will by default test if any of the two can be
+enabled and use it when ``ENABLE_TESTING`` is active.  It can also be
+selected manually through the ``CMAKE_CUSTOM_LINKER`` CMake variable.
+Allowed values are ``lld``, ``gold``, ``bfd``, or ``default``.  The
+``default`` option will use the system default linker otherwise, the
+linker is chosen explicitly.  This option is only available for the
+GNU or Clang C++ compiler.
+
+Tests for other components and utility functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Additional tests that validate utility functions or specific components
+of LAMMPS are implemented as standalone executable which may, or may not
+require creating a suitable LAMMPS instance.  These tests are more specific
+and do not require YAML format input files.  To add a test, either an
+existing source file needs to be extended or a new file added, which in turn
+requires additions to the ``CMakeLists.txt`` file in the source folder.
+
 Collect and visualize code coverage metrics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -288,21 +412,41 @@ 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
+
+Coding style utilities
+----------------------
+
+To aid with enforcing some of the coding style conventions in LAMMPS
+some additional build targets have been added. These require Python 3.5
+or later and will only work on Unix-like operating and file systems.
+The following options are available.
+
+.. code-block:: bash
+
+   make check-whitespace    # generate coverage report in HTML format
+   make fix-whitespace      # generate coverage report in XML format
+   make check-permissions   # delete folder with HTML format coverage report
+   make fix-permissions     # delete all collected coverage data and HTML output
+
+For the code in the ``unittest`` tree we are using the `clang-format`
+tool (Clang version 8.0 or later is required). If available, the source
+code files in the ``unittest`` tree can be updated to conform to the
+formatting settings using ``make format-tests``.

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,97 +45,99 @@ 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.
 
 ----------
 
 .. _cmake_presets:
 
 CMake presets for installing many packages
+""""""""""""""""""""""""""""""""""""""""""
 
 Instead of specifying all the CMake options via the command-line,
 CMake allows initializing its settings cache using script files.
@@ -168,7 +170,8 @@ one of them as a starting point and customize it to your needs.
    in a single cmake run, or change settings incrementally by running
    cmake with new flags.
 
-**Example:**
+Example
+"""""""
 
 .. code-block:: bash
 

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_bash>`
+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_all.rst

@@ -46,13 +46,6 @@ An alphabetic list of all general LAMMPS commands.
    * :doc:`dimension <dimension>`
    * :doc:`displace_atoms <displace_atoms>`
    * :doc:`dump <dump>`
-   * :doc:`dump atom/adios <dump_adios>`
-   * :doc:`dump custom/adios <dump_adios>`
-   * :doc:`dump image <dump_image>`
-   * :doc:`dump movie <dump_image>`
-   * :doc:`dump netcdf <dump_netcdf>`
-   * :doc:`dump netcdf/mpiio <dump_netcdf>`
-   * :doc:`dump vtk <dump_vtk>`
    * :doc:`dump_modify <dump_modify>`
    * :doc:`dynamical_matrix <dynamical_matrix>`
    * :doc:`echo <echo>`
@@ -108,7 +101,8 @@ An alphabetic list of all general LAMMPS commands.
    * :doc:`region <region>`
    * :doc:`replicate <replicate>`
    * :doc:`rerun <rerun>`
-   * :doc:`reset_ids <reset_ids>`
+   * :doc:`reset_atom_ids <reset_atom_ids>`
+   * :doc:`reset_mol_ids <reset_mol_ids>`
    * :doc:`reset_timestep <reset_timestep>`
    * :doc:`restart <restart>`
    * :doc:`run <run>`

doc/src/Commands_bond.rst

@@ -46,6 +46,7 @@ OPT.
    * :doc:`oxdna2/fene <bond_oxdna>`
    * :doc:`oxrna2/fene <bond_oxdna>`
    * :doc:`quartic (o) <bond_quartic>`
+   * :doc:`special <bond_special>`
    * :doc:`table (o) <bond_table>`
 
 .. _angle:

doc/src/Commands_compute.rst

@@ -80,6 +80,7 @@ KOKKOS, o = USER-OMP, t = OPT.
    * :doc:`ke/eff <compute_ke_eff>`
    * :doc:`ke/rigid <compute_ke_rigid>`
    * :doc:`mesont <compute_mesont>`
+   * :doc:`mliap <compute_mliap>`
    * :doc:`momentum <compute_momentum>`
    * :doc:`msd <compute_msd>`
    * :doc:`msd/chunk <compute_msd_chunk>`
@@ -122,6 +123,7 @@ KOKKOS, o = USER-OMP, t = OPT.
    * :doc:`smd/tlsph/strain/rate <compute_smd_tlsph_strain_rate>`
    * :doc:`smd/tlsph/stress <compute_smd_tlsph_stress>`
    * :doc:`smd/triangle/vertices <compute_smd_triangle_vertices>`
+   * :doc:`smd/ulsph/effm <compute_smd_ulsph_effm>`
    * :doc:`smd/ulsph/num/neighs <compute_smd_ulsph_num_neighs>`
    * :doc:`smd/ulsph/strain <compute_smd_ulsph_strain>`
    * :doc:`smd/ulsph/strain/rate <compute_smd_ulsph_strain_rate>`

doc/src/Commands_fix.rst

@@ -42,6 +42,7 @@ OPT.
    * :doc:`bocs <fix_bocs>`
    * :doc:`bond/break <fix_bond_break>`
    * :doc:`bond/create <fix_bond_create>`
+   * :doc:`bond/create/angle <fix_bond_create>`
    * :doc:`bond/react <fix_bond_react>`
    * :doc:`bond/swap <fix_bond_swap>`
    * :doc:`box/relax <fix_box_relax>`
@@ -97,6 +98,7 @@ OPT.
    * :doc:`manifoldforce <fix_manifoldforce>`
    * :doc:`meso/move <fix_meso_move>`
    * :doc:`momentum (k) <fix_momentum>`
+   * :doc:`momentum/chunk <fix_momentum>`
    * :doc:`move <fix_move>`
    * :doc:`mscg <fix_mscg>`
    * :doc:`msst <fix_msst>`
@@ -148,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>`
@@ -243,3 +246,4 @@ OPT.
    * :doc:`wall/region <fix_wall_region>`
    * :doc:`wall/region/ees <fix_wall_ees>`
    * :doc:`wall/srd <fix_wall_srd>`
+   * :doc:`widom <fix_widom>`

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>`
@@ -136,22 +137,22 @@ OPT.
    * :doc:`lj/class2/soft <pair_fep_soft>`
    * :doc:`lj/cubic (go) <pair_lj_cubic>`
    * :doc:`lj/cut (gikot) <pair_lj>`
-   * :doc:`lj/cut/coul/cut (gko) <pair_lj>`
+   * :doc:`lj/cut/coul/cut (gko) <pair_lj_cut_coul>`
    * :doc:`lj/cut/coul/cut/soft (o) <pair_fep_soft>`
-   * :doc:`lj/cut/coul/debye (gko) <pair_lj>`
-   * :doc:`lj/cut/coul/dsf (gko) <pair_lj>`
-   * :doc:`lj/cut/coul/long (gikot) <pair_lj>`
+   * :doc:`lj/cut/coul/debye (gko) <pair_lj_cut_coul>`
+   * :doc:`lj/cut/coul/dsf (gko) <pair_lj_cut_coul>`
+   * :doc:`lj/cut/coul/long (gikot) <pair_lj_cut_coul>`
    * :doc:`lj/cut/coul/long/cs <pair_cs>`
    * :doc:`lj/cut/coul/long/soft (o) <pair_fep_soft>`
-   * :doc:`lj/cut/coul/msm (go) <pair_lj>`
-   * :doc:`lj/cut/coul/wolf (o) <pair_lj>`
+   * :doc:`lj/cut/coul/msm (go) <pair_lj_cut_coul>`
+   * :doc:`lj/cut/coul/wolf (o) <pair_lj_cut_coul>`
    * :doc:`lj/cut/dipole/cut (go) <pair_dipole>`
    * :doc:`lj/cut/dipole/long (g) <pair_dipole>`
    * :doc:`lj/cut/dipole/sf (go) <pair_dipole>`
    * :doc:`lj/cut/soft (o) <pair_fep_soft>`
    * :doc:`lj/cut/thole/long (o) <pair_thole>`
-   * :doc:`lj/cut/tip4p/cut (o) <pair_lj>`
-   * :doc:`lj/cut/tip4p/long (got) <pair_lj>`
+   * :doc:`lj/cut/tip4p/cut (o) <pair_lj_cut_tip4p>`
+   * :doc:`lj/cut/tip4p/long (got) <pair_lj_cut_tip4p>`
    * :doc:`lj/cut/tip4p/long/soft (o) <pair_fep_soft>`
    * :doc:`lj/expand (gko) <pair_lj_expand>`
    * :doc:`lj/expand/coul/long (g) <pair_lj_expand>`
@@ -183,6 +184,7 @@ OPT.
    * :doc:`mesont/tpm <pair_mesont_tpm>`
    * :doc:`mgpt <pair_mgpt>`
    * :doc:`mie/cut (g) <pair_mie>`
+   * :doc:`mliap <pair_mliap>`
    * :doc:`mm3/switch3/coulgauss/long <pair_mm3_switch3_coulgauss_long>`
    * :doc:`momb <pair_momb>`
    * :doc:`morse (gkot) <pair_morse>`
@@ -228,7 +230,6 @@ OPT.
    * :doc:`smd/ulsph <pair_smd_ulsph>`
    * :doc:`smtbq <pair_smtbq>`
    * :doc:`snap (k) <pair_snap>`
-   * :doc:`snap (k) <pair_snap>`
    * :doc:`soft (go) <pair_soft>`
    * :doc:`sph/heatconduction <pair_sph_heatconduction>`
    * :doc:`sph/idealgas <pair_sph_idealgas>`

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/Errors_warnings.rst

@@ -118,6 +118,24 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
    incorrect periodic images of atoms in interaction lists.  To avoid, either use
    :doc:`pair style zero <pair_zero>` with a suitable cutoff or use :doc:`comm_modify cutoff <comm_modify>`.
 
+*Communication cutoff is shorter than a bond length based estimate. This may lead to errors.*
+
+   Since LAMMPS stores topology data with individual atoms, all atoms
+   comprising a bond, angle, dihedral or improper must be present on any
+   sub-domain that "owns" the atom with the information, either as a
+   local or a ghost atom. The communication cutoff is what determines up
+   to what distance from a sub-domain boundary ghost atoms are created.
+   The communication cutoff is by default the largest non-bonded cutoff
+   plus the neighbor skin distance, but for short or non-bonded cutoffs
+   and/or long bonds, this may not be sufficient. This warning indicates
+   that there is an increased risk of a simulation stopping unexpectedly
+   because of Bond/Angle/Dihedral/Improper atoms missing.  It can be
+   silenced by manually setting the communication cutoff via
+   :doc:`comm_modify cutoff <comm_modify>`.  However, since the
+   heuristic used to determine the estimate is not always accurate, it
+   is not changed automatically and the warning may be ignored depending
+   on the specific system being simulated.
+
 *Communication cutoff is too small for SNAP micro load balancing, increased to %lf*
    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_bash
-
 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_bash.rst

@@ -1,264 +0,0 @@
-Using LAMMPS with Bash on Windows
-=================================
-
-**written by Richard Berger**
-
-----------
-
-Starting with Windows 10 you can install Linux tools directly in Windows. This
-allows you to compile LAMMPS following the same procedure as on a real Ubuntu
-Linux installation. Software can be easily installed using the package manager
-via apt-get and all files are accessible in both the Windows Explorer and your
-Linux shell (bash). This avoids switching to a different operating system or
-installing a virtual machine. Everything runs on Windows.
-
-.. seealso::
-
-   You can find more detailed information at the `Windows Subsystem for Linux Installation Guide for Windows 10 <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`_.
-
-Installing Bash on Windows
---------------------------
-
-Prerequisites
-^^^^^^^^^^^^^
-
-* Windows 10 (64bit only)
-* Latest updates installed
-
-Enable developer mode
-^^^^^^^^^^^^^^^^^^^^^
-
-You enable this feature by first opening Windows Settings and enabling
-Developer mode. Go to the Windows settings and search for "developer". This
-will allow you to install software which comes from outside of the Windows
-Store.  You might be prompted to reboot your compute. Please do so.
-
-.. image:: JPG/bow_tutorial_01_small.png
-   :target: JPG/bow_tutorial_01.png
-
-.. image:: JPG/bow_tutorial_02_small.png
-   :target: JPG/bow_tutorial_02.png
-
-.. image:: JPG/bow_tutorial_03_small.png
-   :target: JPG/bow_tutorial_03.png
-
-Install Windows Subsystem for Linux
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Next you must ensure that the Window Subsystem for Linux is installed. Again,
-search for "enable windows features" in the Settings dialog. This opens a
-dialog with a list of features you can install. Add a checkmark to Windows
-Subsystem for Linux (Beta) and press OK.
-
-.. image:: JPG/bow_tutorial_04_small.png
-   :target: JPG/bow_tutorial_04.png
-
-.. image:: JPG/bow_tutorial_05.png
-   :target: JPG/bow_tutorial_05.png
-
-Install Bash for Windows
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-After installation completes, type "bash" in the Windows Start menu search.
-Select the first found option. This will launch a command-line window which
-will prompt you about installing Ubuntu on Windows. Confirm with "y" and press
-enter. This will then download Ubuntu for Windows.
-
-.. image:: JPG/bow_tutorial_06.png
-
-.. image:: JPG/bow_tutorial_07.png
-
-During installation, you will be asked for a new password. This will be used
-for installing new software and running commands with sudo.
-
-.. image:: JPG/bow_tutorial_08.png
-
-Type exit to close the command-line window.
-
-Go to the Start menu and type "bash" again. This time you will see a "Bash on
-Ubuntu on Windows" Icon. Start this program.
-
-.. image:: JPG/bow_tutorial_09.png
-
-Congratulations, you have installed **Bash on Ubuntu on Windows**\ .
-
-.. image:: JPG/bow_tutorial_10.png
-
-----------
-
-Compiling LAMMPS in Bash on Windows
------------------------------------
-
-The installation of LAMMPS in this environment is identical to working inside
-of a real Ubuntu Linux installation. At the time writing, it uses Ubuntu 16.04.
-
-Installing prerequisite packages
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-First upgrade all existing packages using
-
-.. code-block:: bash
-
-   sudo apt update
-   sudo apt upgrade -y
-
-Next install the following packages, which include compilers and libraries
-needed for various LAMMPS features:
-
-.. code-block:: bash
-
-   sudo apt install -y build-essential ccache gfortran openmpi-bin libopenmpi-dev libfftw3-dev libjpeg-dev libpng-dev python-dev python-virtualenv libblas-dev liblapack-dev libhdf5-serial-dev hdf5-tools
-
-Files in Ubuntu on Windows
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When you launch "Bash on Ubuntu on Windows" you will start out in your Linux
-user home directory /home/[username]\ . You can access your Windows user directory
-using the /mnt/c/Users/[username] folder.
-
-Download LAMMPS
-^^^^^^^^^^^^^^^
-
-Obtain a copy of the LAMMPS code and go into it using "cd"
-
-Option 1: Downloading LAMMPS tarball using wget
-"""""""""""""""""""""""""""""""""""""""""""""""
-
-.. code-block:: bash
-
-   wget https://lammps.sandia.gov/tars/lammps-stable.tar.gz
-   tar xvzf lammps-stable.tar.gz
-   cd lammps-31Mar17
-
-Option 2: Obtaining LAMMPS code from GitHub
-"""""""""""""""""""""""""""""""""""""""""""
-
-.. code-block:: bash
-
-   git clone https://github.com/lammps/lammps.git
-   cd lammps
-
-Compiling LAMMPS
-^^^^^^^^^^^^^^^^
-
-At this point you can compile LAMMPS like on Ubuntu Linux.
-
-Compiling serial version
-""""""""""""""""""""""""
-
-.. code-block:: bash
-
-   cd src/
-   make -j 4 serial
-
-This will create an executable called lmp_serial in the src/ directory
-
-Compiling MPI version
-"""""""""""""""""""""
-
-.. code-block:: bash
-
-   cd src/
-   make -j 4 mpi
-
-This will create an executable called lmp_mpi in the src/ directory
-
-----------
-
-Finally, please note the absolute path of your src folder. You can get this using
-
-.. code-block:: bash
-
-   pwd
-
-or
-
-.. code-block:: bash
-
-   echo $PWD
-
-To run any examples you need the location of the executable. For now, let us
-save this location in a temporary variable
-
-.. code-block:: bash
-
-   LAMMPS_DIR=$PWD
-
-----------
-
-Running an example script
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Once compiled you can execute some of the LAMMPS examples. Switch into the
-examples/melt folder
-
-.. code-block:: bash
-
-   cd ../examples/melt
-
-The full path of the serial executable is $LAMMPS_DIR/lmp_serial, while the mpi
-version is $LAMMPS_DIR/lmp_mpi. You can run the melt example with either
-version as follows:
-
-.. code-block:: bash
-
-   $LAMMPS_DIR/lmp_serial -in in.melt
-
-or
-
-.. code-block:: bash
-
-   mpirun -np 4 $LAMMPS_DIR/lmp_mpi -in in.melt
-
-Note the use of our variable $LAMMPS_DIR, which expands into the full path of
-the LAMMPS src folder we saved earlier.
-
-Adding your executable directory to your PATH
-"""""""""""""""""""""""""""""""""""""""""""""
-
-You can avoid having to type the full path of your LAMMPS binary by adding its
-parent folder to the PATH environment variable as follows:
-
-.. code-block:: bash
-
-   export PATH=$LAMMPS_DIR:$PATH
-
-Input scripts can then be run like this:
-
-.. code-block:: bash
-
-   lmp_serial -in in.melt
-
-or
-
-.. code-block:: bash
-
-   mpirun -np 4 lmp_mpi -in in.melt
-
-However, this PATH variable will not persist if you close your bash window.
-To persist this setting edit the $HOME/.bashrc file using your favorite editor
-and add this line
-
-.. code-block:: bash
-
-   export PATH=/full/path/to/your/lammps/src:$PATH
-
-**Example:**
-
-For an executable lmp_serial with a full path
-
-.. code-block:: bash
-
-   /home/richard/lammps/src/lmp_serial
-
-the PATH variable should be
-
-.. code-block:: bash
-
-   export PATH=/home/richard/lammps/src:$PATH
-
-.. note::
-
-   This should give you a jump start when trying to run LAMMPS on Windows.
-   To become effective in this environment I encourage you to look into Linux
-   tutorials explaining Bash and Basic Unix commands (e.g., `Linux Journey <https://linuxjourney.com>`_)

doc/src/Howto_bioFF.rst

@@ -102,8 +102,8 @@ documentation for the formula it computes.
 * :doc:`pair_style <pair_buck>` buck/coul/cut
 * :doc:`pair_style <pair_buck>` buck/coul/long
 * :doc:`pair_style <pair_lj>` lj/cut
-* :doc:`pair_style <pair_lj>` lj/cut/coul/cut
-* :doc:`pair_style <pair_lj>` lj/cut/coul/long
+* :doc:`pair_style <pair_lj_cut_coul>` lj/cut/coul/cut
+* :doc:`pair_style <pair_lj_cut_coul>` lj/cut/coul/long
 
 * :doc:`pair_style <pair_hbond_dreiding>` hbond/dreiding/lj
 * :doc:`pair_style <pair_hbond_dreiding>` hbond/dreiding/morse

doc/src/Howto_body.rst

@@ -9,13 +9,15 @@ surface meshes of discrete points, collections of sub-particles,
 deformable objects, etc.  Note that other kinds of finite-size
 spherical and aspherical particles are also supported by LAMMPS, such
 as spheres, ellipsoids, line segments, and triangles, but they are
-simpler entities that body particles.  See the :doc:`Howto spherical <Howto_spherical>` doc page for a general overview of all
-these particle types.
+simpler entities than body particles.  See the :doc:`Howto spherical
+<Howto_spherical>` doc page for a general overview of all these
+particle types.
 
 Body particles are used via the :doc:`atom_style body <atom_style>`
 command.  It takes a body style as an argument.  The current body
 styles supported by LAMMPS are as follows.  The name in the first
-column is used as the *bstyle* argument for the :doc:`atom_style body <atom_style>` command.
+column is used as the *bstyle* argument for the :doc:`atom_style body
+<atom_style>` command.
 
 +----------------------+---------------------------------------------------+
 | *nparticle*          | rigid body with N sub-particles                   |
@@ -30,8 +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.
 
 ----------
 
@@ -55,10 +58,10 @@ interactions, building neighbor lists, migrating particles between
 processors, output of particles to a dump file, etc.  This means that
 interactions between pairs of bodies or between a body and non-body
 (point) particle need to be encoded in an appropriate pair style.  If
-such a pair style were to mimic the :doc:`fix rigid <fix_rigid>` model,
-it would need to loop over the entire collection of interactions
-between pairs of simple particles within the two bodies, each time a
-single body/body interaction was computed.
+such a pair style were to mimic the :doc:`fix rigid <fix_rigid>`
+model, it would need to loop over the entire collection of
+interactions between pairs of simple particles within the two bodies,
+each time a single body/body interaction was computed.
 
 Thus it only makes sense to use body particles and develop such a pair
 style, when particle/particle interactions are more complex than what
@@ -160,27 +163,6 @@ of the body particle.
 The :doc:`pair_style body/nparticle <pair_body_nparticle>` command can be used
 with this body style to compute body/body and body/non-body interactions.
 
-For output purposes via the :doc:`compute body/local <compute_body_local>` and :doc:`dump local <dump>`
-commands, this body style produces one datum for each of the N
-sub-particles in a body particle.  The datum has 3 values:
-
-.. parsed-literal::
-
-   1 = x position of sub-particle
-   2 = y position of sub-particle
-   3 = z position of sub-particle
-
-These values are the current position of the sub-particle within the
-simulation domain, not a displacement from the center-of-mass (COM) of
-the body particle itself.  These values are calculated using the
-current COM and orientation of the body particle.
-
-For images created by the :doc:`dump image <dump_image>` command, if the
-*body* keyword is set, then each body particle is drawn as a
-collection of spheres, one for each sub-particle.  The size of each
-sphere is determined by the *bflag1* parameter for the *body* keyword.
-The *bflag2* argument is ignored.
-
 ----------
 
 **Specifics of body style rounded/polygon:**
@@ -208,7 +190,7 @@ The Nmin and Nmax arguments are used to bound the size of data
 structures used internally by each particle.
 
 When the :doc:`read_data <read_data>` command reads a data file for this
-body style, the following information must be provided for each entry
+body style, the following information must be provided for each body
 in the *Bodies* section of the data file:
 
 .. parsed-literal::
@@ -219,21 +201,25 @@ in the *Bodies* section of the data file:
    x1 y1 z1
    ...
    xN yN zN
-   i j j k k ...
    diameter
 
-where M = 6 + 3\*N + 2\*N + 1, and N is the number of vertices in the
-body particle.
+where M = 6 + 3\*N + 1, and N is the number of vertices in the body
+particle.
 
 The integer line has a single value N.  The floating point line(s)
-list 6 moments of inertia followed by the coordinates of the N
+list 6 moments of inertia, followed by the coordinates of the N
 vertices (x1 to zN) as 3N values (with z = 0.0 for each), followed by
-2N vertex indices corresponding to the end points of the N edges,
-followed by a single diameter value = the rounded diameter of the
-circle that surrounds each vertex. The diameter value can be different
-for each body particle. These floating-point values can be listed on
-as many lines as you wish; see the :doc:`read_data <read_data>` command
-for more details.
+a diameter value = the rounded diameter of the circle that surrounds
+each vertex. The diameter value can be different for each body
+particle. These floating-point values can be listed on as many lines
+as you wish; see the :doc:`read_data <read_data>` command for more
+details.
+
+.. note::
+
+  It is important that the vertices for each polygonal body particle be
+  listed in order around its perimeter, so that edges can be inferred.
+  LAMMPS does not check that this is the case.
 
 The 6 moments of inertia (ixx,iyy,izz,ixy,ixz,iyz) should be the
 values consistent with the current orientation of the rigid body
@@ -260,10 +246,6 @@ is consistent with the 6 moments of inertia: ixx iyy izz ixy ixz iyz =
    -0.7071 0.7071 0
    0.7071 0.7071 0
    0.7071 -0.7071 0
-   0 1
-   1 2
-   2 3
-   3 0
    1.0
 
 A rod in 2D, whose length is 4.0, mass 1.0, rounded at two ends
@@ -345,8 +327,10 @@ in the *Bodies* section of the data file:
    1 2 3 4
    diameter
 
-where M = 6 + 3\*N + 2\*E + 4\*F + 1, and N is the number of vertices in
-the body particle, E = number of edges, F = number of faces.
+where M = 6 + 3\*N + 2\*E + 4\*F + 1, and N is the number of vertices
+in the body particle, E = number of edges, F = number of faces.  For N
+= 1 or 2, the format is simpler.  E and F are ignored and no edges or
+faces are listed, so that M = 6 + 3\*N + 1.
 
 The integer line has three values: number of vertices (N), number of
 edges (E) and number of faces (F). The floating point line(s) list 6
@@ -356,16 +340,26 @@ the end points of the E edges, then 4\*F vertex indices defining F
 faces.  The last value is the diameter value = the rounded diameter of
 the sphere that surrounds each vertex. The diameter value can be
 different for each body particle. These floating-point values can be
-listed on as many lines as you wish; see the
-:doc:`read_data <read_data>` command for more details.  Because the
-maximum number of vertices per face is hard-coded to be 4
-(i.e. quadrilaterals), faces with more than 4 vertices need to be
-split into triangles or quadrilaterals.  For triangular faces, the
-last vertex index should be set to -1.
+listed on as many lines as you wish; see the :doc:`read_data
+<read_data>` command for more details.
 
-The ordering of the 4 vertices within a face should follow
-the right-hand rule so that the normal vector of the face points
-outwards from the center of mass.
+Note that vertices are numbered from 0 to N-1 inclusive.  The order of
+the 2 vertices in each edge does not matter.  Faces can be triangles
+or quadrilaterals.  In both cases 4 vertices must be specified.  For a
+triangle the 4th vertex is -1.  The 4 vertices within each triangle or
+quadrilateral face should be ordered by the right-hand rule so that
+the normal vector of the face points outwards from the center of mass.
+For polyhedron with faces with more than 4 vertices, you should split
+the complex face into multiple simple faces, each of which is a
+triangle or quadrilateral.
+
+.. note::
+
+  If a face is a quadrilateral then its 4 vertices must be co-planar.
+  LAMMPS does not check that this is the case.  If you have a quad-face
+  of a polyhedron that is not planar (e.g. a cube whose vertices have
+  been randomly displaced), then you should represent the single quad
+  face as two triangle faces instead.
 
 The 6 moments of inertia (ixx,iyy,izz,ixy,ixz,iyz) should be the
 values consistent with the current orientation of the rigid body
@@ -421,8 +415,8 @@ by circles of diameter 0.5, is specified as follows:
 
 .. parsed-literal::
 
-   1 1 13
-   2
+   1 3 13
+   2 1 1
    0 1.33333 1.33333 0 0 0
    -2 0 0
    2 0 0
@@ -432,27 +426,34 @@ A sphere whose diameter is 3.0 and mass 1.0, is specified as follows:
 
 .. parsed-literal::
 
-   1 1 10
-   1
+   1 3 10
+   1 1 1
    0.9 0.9 0.9 0 0 0
    0 0 0
    3.0
 
-The :doc:`pair_style body/rounded/polhedron <pair_body_rounded_polyhedron>` command can
-be used with this body style to compute body/body interactions.  The
-:doc:`fix wall/body/polyhedron <fix_wall_body_polygon>` command can be
-used with this body style to compute the interaction of body particles
-with a wall.
+The number of edges and faces for a rod or sphere must be listed,
+but is ignored.
+
+The :doc:`pair_style body/rounded/polhedron
+<pair_body_rounded_polyhedron>` command can be used with this body
+style to compute body/body interactions.  The :doc:`fix
+wall/body/polyhedron <fix_wall_body_polygon>` command can be used with
+this body style to compute the interaction of body particles with a
+wall.
 
 ----------
 
-For output purposes via the :doc:`compute body/local <compute_body_local>` and :doc:`dump local <dump>`
-commands, this body style produces one datum for each of the N
-sub-particles in a body particle.  The datum has 3 values:
+**Output specifics for all body styles:**
+
+For the :doc:`compute body/local <compute_body_local>` and :doc:`dump
+local <dump>` commands, all 3 of the body styles described on his page
+produces one datum for each of the N vertices (of sub-particles) in a
+body particle.  The datum has 3 values:
 
 .. parsed-literal::
 
-   1 = x position of vertex
+   1 = x position of vertex (or sub-particle)
    2 = y position of vertex
    3 = z position of vertex
 
@@ -461,15 +462,29 @@ simulation domain, not a displacement from the center-of-mass (COM) of
 the body particle itself.  These values are calculated using the
 current COM and orientation of the body particle.
 
-For images created by the :doc:`dump image <dump_image>` command, if the
-*body* keyword is set, then each body particle is drawn as a polygon
-consisting of N line segments.  Note that the line segments are drawn
-between the N vertices, which does not correspond exactly to the
-physical extent of the body (because the :doc:`pair_style rounded/polygon <pair_body_rounded_polygon>` defines finite-size
-spheres at those point and the line segments between the spheres are
-tangent to the spheres).  The drawn diameter of each line segment is
-determined by the *bflag1* parameter for the *body* keyword.  The
-*bflag2* argument is ignored.
+The :doc:`dump image <dump_image>` command and its *body* keyword can
+be used to render body particles.
+
+For the *nparticle* body style, each body is drawn as a
+collection of spheres, one for each sub-particle.  The size of each
+sphere is determined by the *bflag1* parameter for the *body* keyword.
+The *bflag2* argument is ignored.
+
+For the *rounded/polygon* body style, each body is drawn as a polygon
+with N line segments.  For the *rounded/polyhedron* body style, each
+face of each body is drawn as a polygon with N line segments.  The
+drawn diameter of each line segment is determined by the *bflag1*
+parameter for the *body* keyword.  The *bflag2* argument is ignored.
+
+Note that for both the *rounded/polygon* and *rounded/polyhedron*
+styles, line segments are drawn between the pairs of vertices.
+Depending on the diameters of the line segments this may be slightly
+different than the physical extent of the body as calculated by the
+:doc:`pair_style rounded/polygon <pair_body_rounded_polygon>` or
+:doc:`pair_style rounded/polyhedron <pair_body_rounded_polyhedron>`
+commands.  Conceptually, the pair styles define the surface of a 2d or
+3d body by lines or planes that are tangent to the finite-size spheres
+of specified diameter which are placed on each vertex position.
 
 ----------
 

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

@@ -47,7 +47,7 @@ using a shell like Bash.
 
 - Linux: any Terminal window will work
 - MacOS X: launch the Terminal application.
-- Windows 10: install and run the :doc:`Windows subsystem for Linux <Howto_bash>`
+- Windows 10: install and run the :doc:`Windows Subsystem for Linux <Howto_wsl>`
 
 We also assume that you have downloaded and unpacked a recent LAMMPS source code package
 or used Git to create a clone of the LAMMPS sources on your compilation machine.
@@ -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,10 +328,12 @@ 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``
-     - common compiler flags, for optimization or instrumentation (default: compiler specific)
+     - common compiler flags, for optimization or instrumentation (default:)
    * - ``LAMMPS_MACHINE``
      - when set to ``name`` the LAMMPS executable and library will be called ``lmp_name`` and ``liblammps_name.a``
    * - ``LAMMPS_EXCEPTIONS``

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: