Merge pull request #2374 from akohlmey/next_patch_version

Step version strings for the next patch release

.gitattributes

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

.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

cmake/CMakeLists.txt

@@ -218,10 +218,9 @@ if(BUILD_OMP)
     message(FATAL_ERROR "Cannot find the 'omp.h' header file required for full OpenMP support")
   endif()
 
-  if (((CMAKE_CXX_COMPILER_ID STREQUAL "GNU") AND (CMAKE_CXX_COMPILER_VERSION VERSION_GREATER 8.99.9)) OR
-      ((CMAKE_CXX_COMPILER_ID STREQUAL "Clang") AND (CMAKE_CXX_COMPILER_VERSION VERSION_GREATER 9.99.9)) OR
-      ((CMAKE_CXX_COMPILER_ID STREQUAL "Intel") AND (CMAKE_CXX_COMPILER_VERSION VERSION_GREATER 18.99.9))
-      )
+  if (((CMAKE_CXX_COMPILER_ID STREQUAL "GNU") AND (CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 9.0)) OR
+      ((CMAKE_CXX_COMPILER_ID STREQUAL "Clang") AND (CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 10.0)) OR
+      ((CMAKE_CXX_COMPILER_ID STREQUAL "Intel") AND (CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 19.0)))
     # GCC 9.x and later plus Clang 10.x and later implement strict OpenMP 4.0 semantics for consts.
     # Intel 18.0 was tested to support both, so we switch to OpenMP 4+ from 19.x onward to be safe.
     target_compile_definitions(lammps PRIVATE -DLAMMPS_OMP_COMPAT=4)
@@ -249,6 +248,26 @@ if(${CMAKE_CXX_COMPILER_ID} STREQUAL "GNU")
   endif()
 endif()
 
+#######################################
+# add custom target for IWYU analysis
+#######################################
+set(ENABLE_IWYU OFF CACHE BOOL "Add 'iwyu' build target to call the include-what-you-use tool")
+mark_as_advanced(ENABLE_IWYU)
+if(ENABLE_IWYU)
+  find_program(IWYU_EXE NAMES include-what-you-use iwyu)
+  find_program(IWYU_TOOL NAMES iwyu_tool iwyu-tool iwyu_tool.py)
+  if (IWYU_EXE AND IWYU_TOOL)
+    add_custom_target(
+      iwyu
+      ${IWYU_TOOL} -o clang -p ${CMAKE_CURRENT_BINARY_DIR} -- -Xiwyu --mapping_file=${CMAKE_CURRENT_SOURCE_DIR}/iwyu/iwyu-extra-map.imp
+      COMMENT "Running IWYU")
+    add_dependencies(iwyu lammps)
+  else()
+    message(FATAL_ERROR "To use IWYU you need the include-what-you-use/iwyu executable"
+      "and the iwyu-tool/iwyu_tool script installed in your PATH")
+  endif()
+endif()
+
 set(ENABLE_SANITIZER "none" CACHE STRING "Select a code sanitizer option (none (default), address, leak, thread, undefined)")
 mark_as_advanced(ENABLE_SANITIZER)
 set(ENABLE_SANITIZER_VALUES none address leak thread undefined)
@@ -293,14 +312,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)
@@ -747,6 +765,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()

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}

cmake/Modules/Packages/COMPRESS.cmake

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

cmake/Modules/Packages/GPU.cmake

@@ -75,7 +75,7 @@ if(GPU_API STREQUAL "CUDA")
   endif()
   # Kepler (GPU Arch 3.5) is supported by CUDA 5 to CUDA 11
   if((CUDA_VERSION VERSION_GREATER_EQUAL "5.0") AND (CUDA_VERSION VERSION_LESS "12.0"))
-    string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_30,code=[sm_30,compute_30] -gencode arch=compute_35,code=[sm_35,compute_35]")
+    string(APPEND GPU_CUDA_GENCODE " -gencode arch=compute_35,code=[sm_35,compute_35]")
   endif()
   # Maxwell (GPU Arch 5.x) is supported by CUDA 6 and later
   if(CUDA_VERSION VERSION_GREATER_EQUAL "6.0")

cmake/Modules/Packages/KOKKOS.cmake

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

cmake/Modules/Packages/KSPACE.cmake

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

cmake/Modules/Packages/MSCG.cmake

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

cmake/Modules/Packages/PYTHON.cmake

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

cmake/Modules/Packages/USER-COLVARS.cmake

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

cmake/Modules/Packages/USER-MOLFILE.cmake

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

cmake/Modules/Packages/USER-PLUMED.cmake

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

cmake/Modules/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

@@ -16,6 +16,36 @@ if(ENABLE_TESTING)
   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()

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 ] },
+]

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)
@@ -33,16 +47,24 @@ HAS_PDFLATEX = YES
 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 "  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 +79,33 @@ help:
 # ------------------------------------------
 
 clean-all: clean
-	rm -rf $(BUILDDIR)/docenv $(BUILDDIR)/doctrees $(BUILDDIR)/mathjax Manual.pdf Developer.pdf
+	rm -rf $(BUILDDIR)/docenv $(MATHJAX) $(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 +114,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 +149,14 @@ mobi: epub
 	@ebook-convert LAMMPS.epub LAMMPS.mobi
 	@echo "Conversion finished. The MOBI manual file is created."
 
-pdf: $(ANCHORCHECK)
+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 was not found! Please check README.md 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 ;\
@@ -144,9 +172,9 @@ pdf: $(ANCHORCHECK)
 		mv tmp.tex LAMMPS.tex && \
 		sed 's/\\end{equation}//g' LAMMPS.tex > tmp.tex && \
 		mv tmp.tex LAMMPS.tex && \
-		make && \
-		make && \
-		make && \
+		$(MAKE) $(MFLAGS) && \
+		$(MAKE) $(MFLAGS) && \
+		$(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,33 @@ 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 $@
+
+$(POLYFILL): $(MATHJAX)
+	@curl -s -o $@ "https://polyfill.io/v3/polyfill.min.js?features=es6"
 
 $(TXT2RST) $(ANCHORCHECK): $(VENV)
 	@( \

doc/README

@@ -1,97 +1,60 @@
 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
+Developer.pdf     PDF with info about how LAMMPS is structured
+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
+mathjax           code and fonts for rendering math in html
+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).
+Manual_www.pdf/Developer_www.pdf files.  These files 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 +68,13 @@ to be installed (e.g. from texlive):
 - tabulary
 - upquote
 - wrapfig
+
+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,532 @@
+# 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@/lmptype.h                 \
+                         @LAMMPS_SOURCE_DIR@/atom.cpp                  \
+                         @LAMMPS_SOURCE_DIR@/atom.h                    \
+                         @LAMMPS_SOURCE_DIR@/input.cpp                 \
+                         @LAMMPS_SOURCE_DIR@/input.h                   \
+                         @LAMMPS_SOURCE_DIR@/tokenizer.cpp             \
+                         @LAMMPS_SOURCE_DIR@/tokenizer.h               \
+                         @LAMMPS_SOURCE_DIR@/text_file_reader.cpp      \
+                         @LAMMPS_SOURCE_DIR@/text_file_reader.h        \
+                         @LAMMPS_SOURCE_DIR@/potential_file_reader.cpp \
+                         @LAMMPS_SOURCE_DIR@/potential_file_reader.h   \
+                         @LAMMPS_SOURCE_DIR@/my_page.cpp               \
+                         @LAMMPS_SOURCE_DIR@/my_page.h                 \
+                         @LAMMPS_SOURCE_DIR@/my_pool_chunk.cpp         \
+                         @LAMMPS_SOURCE_DIR@/my_pool_chunk.h           \
+                         @LAMMPS_SOURCE_DIR@/math_eigen.h              \
+
+# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
+# directories that are symbolic links (a Unix file system feature) are excluded
+# from the input.
+# The default value is: NO.
+
+EXCLUDE_SYMLINKS       = YES
+
+#---------------------------------------------------------------------------
+# Configuration options related to output
+#---------------------------------------------------------------------------
+
+GENERATE_HTML          = NO
+GENERATE_LATEX         = NO
+GENERATE_XML           = YES
+XML_OUTPUT             = xml
+XML_PROGRAMLISTING     = YES
+XML_NS_MEMB_FILE_SCOPE = NO
+
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+
+# If the ENABLE_PREPROCESSING tag is set to YES, doxygen will evaluate all
+# C-preprocessor directives found in the sources and include files.
+# The default value is: YES.
+
+#ENABLE_PREPROCESSING   = YES
+ENABLE_PREPROCESSING   = NO
+
+# If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names
+# in the source code. If set to NO, only conditional compilation will be
+# performed. Macro expansion can be done in a controlled way by setting
+# EXPAND_ONLY_PREDEF to YES.
+# The default value is: NO.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
+
+MACRO_EXPANSION        = NO
+
+# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
+# the macro expansion is limited to the macros specified with the PREDEFINED and
+# EXPAND_AS_DEFINED tags.
+# The default value is: NO.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
+
+EXPAND_ONLY_PREDEF     = NO
+
+# If the SEARCH_INCLUDES tag is set to YES, the include files in the
+# INCLUDE_PATH will be searched if a #include is found.
+# The default value is: YES.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
+
+SEARCH_INCLUDES        = YES
+
+# The INCLUDE_PATH tag can be used to specify one or more directories that
+# contain include files that are not input files but should be processed by the
+# preprocessor.
+# This tag requires that the tag SEARCH_INCLUDES is set to YES.
+
+INCLUDE_PATH           =
+
+# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
+# patterns (like *.h and *.hpp) to filter out the header-files in the
+# directories. If left blank, the patterns specified with FILE_PATTERNS will be
+# used.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
+
+INCLUDE_FILE_PATTERNS  =
+
+# The PREDEFINED tag can be used to specify one or more macro names that are
+# defined before the preprocessor is started (similar to the -D option of e.g.
+# gcc). The argument of the tag is a list of macros of the form: name or
+# name=definition (no spaces). If the definition and the "=" are omitted, "=1"
+# is assumed. To prevent a macro definition from being undefined via #undef or
+# recursively expanded use the := operator instead of the = operator.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
+
+PREDEFINED             =
+
+# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
+# tag can be used to specify a list of macro names that should be expanded. The
+# macro definition that is found in the sources will be used. Use the PREDEFINED
+# tag if you want to use a different macro definition that overrules the
+# definition found in the source code.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
+
+EXPAND_AS_DEFINED      =
+
+# If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will
+# remove all references to function-like macros that are alone on a line, have
+# an all uppercase name, and do not end with a semicolon. Such function macros
+# are typically used for boiler-plate code, and will confuse the parser if not
+# removed.
+# The default value is: YES.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
+
+SKIP_FUNCTION_MACROS   = YES
+

doc/github-development-workflow.md

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

doc/graphviz/.gitignore

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

doc/graphviz/Makefile

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

doc/graphviz/lammps-classes.dot

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

doc/include-file-conventions.md

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

doc/lammps.1

@@ -1,4 +1,4 @@
-.TH LAMMPS "21 July 2020" "2020-07-21"
+.TH LAMMPS "18 September 2020" "2020-09-18"
 .SH NAME
 .B LAMMPS
 \- Molecular Dynamics Simulator.

doc/src/Build_basics.rst

@@ -32,74 +32,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 +121,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
@@ -145,18 +151,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.
+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.
 
 ----------
 
@@ -185,131 +192,139 @@ for their compile/link environments, you can often access different
 compilers by simply loading the appropriate module before building
 LAMMPS.
 
-**CMake build**\ :
+.. tabs::
 
-By default CMake will use a compiler it finds according to internal
-preferences and it will add optimization flags appropriate to that
-compiler and any :doc:`accelerator packages <Speed_packages>` you have
-included in the build.
+   .. tab:: CMake build
 
-You can tell CMake to look for a specific compiler with setting CMake
-variables (listed below) during configuration.  For a few common
-choices, there are also presets in the ``cmake/presets`` folder.  For
-convenience, there is a ``CMAKE_TUNE_FLAGS`` variable that can be set to
-apply global compiler options (applied to compilation only), to be used
-for adding compiler or host specific optimization flags in addition to
-the "flags" variables listed below. You may also specify the
-corresponding ``CMAKE_*_FLAGS`` variables individually, if you want to
-experiment with alternate optimization flags.  You should specify all 3
-compilers, so that the (few) LAMMPS source files written in C or Fortran
-are built with a compiler consistent with the one used for the C++
-files:
+      By default CMake will use the compiler it finds according to
+      internal preferences and it will add optimization flags
+      appropriate to that compiler and any :doc:`accelerator packages
+      <Speed_packages>` you have included in the build.  CMake will
+      check if the detected or selected compiler is compatible with the
+      C++ support requirements of LAMMPS and stop with an error, if this
+      is not the case.
 
-.. code-block:: bash
+      You can tell CMake to look for a specific compiler with setting
+      CMake variables (listed below) during configuration.  For a few
+      common choices, there are also presets in the ``cmake/presets``
+      folder.  For convenience, there is a ``CMAKE_TUNE_FLAGS`` variable
+      that can be set to apply global compiler options (applied to
+      compilation only), to be used for adding compiler or host specific
+      optimization flags in addition to the "flags" variables listed
+      below. You may also specify the corresponding ``CMAKE_*_FLAGS``
+      variables individually, if you want to experiment with alternate
+      optimization flags.  You should specify all 3 compilers, so that
+      the (few) LAMMPS source files written in C or Fortran are built
+      with a compiler consistent with the one used for the C++ files:
 
-   -D CMAKE_CXX_COMPILER=name            # name of C++ compiler
-   -D CMAKE_C_COMPILER=name              # name of C compiler
-   -D CMAKE_Fortran_COMPILER=name        # name of Fortran compiler
+      .. code-block:: bash
 
-   -D CMAKE_CXX_FLAGS=string             # flags to use with C++ compiler
-   -D CMAKE_C_FLAGS=string               # flags to use with C compiler
-   -D CMAKE_Fortran_FLAGS=string         # flags to use with Fortran compiler
+         -D CMAKE_CXX_COMPILER=name            # name of C++ compiler
+         -D CMAKE_C_COMPILER=name              # name of C compiler
+         -D CMAKE_Fortran_COMPILER=name        # name of Fortran compiler
 
-A few example command lines are:
+         -D CMAKE_CXX_FLAGS=string             # flags to use with C++ compiler
+         -D CMAKE_C_FLAGS=string               # flags to use with C compiler
+         -D CMAKE_Fortran_FLAGS=string         # flags to use with Fortran compiler
 
-.. code-block:: bash
+      A few example command lines are:
 
-   # Building with GNU Compilers:
-   cmake ../cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DCMAKE_Fortran_COMPILER=gfortran
-   # Building with Intel Compilers:
-   cmake ../cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort
-   # Building with LLVM/Clang Compilers:
-   cmake ../cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_Fortran_COMPILER=flang
+      .. code-block:: bash
 
-For compiling with the Clang/LLVM compilers a CMake preset is provided that
-can be loaded with `-C ../cmake/presets/clang.cmake`.  Similarly,
-`-C ../cmake/presets/intel.cmake` should switch the
+         # Building with GNU Compilers:
+         cmake ../cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DCMAKE_Fortran_COMPILER=gfortran
+         # Building with Intel Compilers:
+         cmake ../cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort
+         # Building with LLVM/Clang Compilers:
+         cmake ../cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_Fortran_COMPILER=flang
 
-In addition you can set ``CMAKE_TUNE_FLAGS`` to specifically add
-compiler flags to tune for optimal performance on given hosts. By
-default this variable is empty.
+      For compiling with the Clang/LLVM compilers a CMake preset is
+      provided that can be loaded with
+      `-C ../cmake/presets/clang.cmake`.  Similarly,
+      `-C ../cmake/presets/intel.cmake` should switch the compiler
+      toolchain to the Intel compilers.
 
-.. note::
+      In addition you can set ``CMAKE_TUNE_FLAGS`` to specifically add
+      compiler flags to tune for optimal performance on given hosts. By
+      default this variable is empty.
 
-   When the cmake command completes, it prints a summary to the screen
-   which compilers it is using and what flags and settings will be used
-   for the  compilation.  Note that if the top-level compiler is mpicxx,
-   it is simply a wrapper on a real compiler.  The underlying compiler
-   info is what CMake will try to determine and report.  You should check
-   to confirm you are using the compiler and optimization flags you want.
+      .. note::
 
-**Makefile.machine settings for traditional make**\ :
+         When the cmake command completes, it prints a summary to the
+         screen which compilers it is using and what flags and settings
+         will be used for the compilation.  Note that if the top-level
+         compiler is mpicxx, it is simply a wrapper on a real compiler.
+         The underlying compiler info is what CMake will try to
+         determine and report.  You should check to confirm you are
+         using the compiler and optimization flags you want.
 
-The "compiler/linker settings" section of a Makefile.machine lists
-compiler and linker settings for your C++ compiler, including
-optimization flags.  For a parallel build it is recommended to use
-``mpicxx`` or ``mpiCC``, since these compiler wrappers will include a
-variety of settings appropriate for your MPI installation and thus
-avoiding the guesswork of finding the right flags.
+   .. tab:: Makefile.machine settings for traditional make
 
-Parallel build (see ``src/MAKE/Makefile.mpi``):
+      The "compiler/linker settings" section of a Makefile.machine lists
+      compiler and linker settings for your C++ compiler, including
+      optimization flags.  For a parallel build it is recommended to use
+      ``mpicxx`` or ``mpiCC``, since these compiler wrappers will
+      include a variety of settings appropriate for your MPI
+      installation and thus avoiding the guesswork of finding the right
+      flags.
 
-.. code-block:: bash
+      Parallel build (see ``src/MAKE/Makefile.mpi``):
 
-   CC =            mpicxx
-   CCFLAGS =       -g -O3
-   LINK =          mpicxx
-   LINKFLAGS =     -g -O
+      .. code-block:: bash
 
-Serial build with GNU gcc (see ``src/MAKE/Makefile.serial``):
+         CC =            mpicxx
+         CCFLAGS =       -g -O3
+         LINK =          mpicxx
+         LINKFLAGS =     -g -O
 
-.. code-block:: make
+      Serial build with GNU gcc (see ``src/MAKE/Makefile.serial``):
 
-   CC =            g++
-   CCFLAGS =       -g -O3
-   LINK =          g++
-   LINKFLAGS =     -g -O
+      .. code-block:: make
 
+         CC =            g++
+         CCFLAGS =       -g -O3
+         LINK =          g++
+         LINKFLAGS =     -g -O
 
-.. note::
+      .. note::
 
-   If compilation stops with a message like the following:
+         If compilation stops with a message like the following:
 
-   .. code-block::
+         .. code-block::
 
-      g++ -g -O3  -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64    -I../STUBS     -c ../main.cpp
-      In file included from ../pointers.h:24:0,
-                 from ../input.h:17,
-                 from ../main.cpp:16:
-      ../lmptype.h:34:2: error: #error LAMMPS requires a C++11 (or later) compliant compiler. Enable C++11 compatibility or upgrade the compiler.
+            g++ -g -O3  -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64    -I../STUBS     -c ../main.cpp
+            In file included from ../pointers.h:24:0,
+                       from ../input.h:17,
+                       from ../main.cpp:16:
+            ../lmptype.h:34:2: error: #error LAMMPS requires a C++11 (or later) compliant compiler. Enable C++11 compatibility or upgrade the compiler.
 
-   then you have either an unsupported (old) compiler or you have to
-   turn on C++11 mode.  The latter applies to GCC 4.8.x shipped with
-   RHEL 7.x and CentOS 7.x.  For those compilers, you need to add the
-   ``-std=c++11`` flag.  Otherwise, you would have to install a newer
-   compiler that supports C++11; either as a binary package or through
-   compiling from source.
+         then you have either an unsupported (old) compiler or you have
+         to turn on C++11 mode.  The latter applies to GCC 4.8.x shipped
+         with RHEL 7.x and CentOS 7.x.  For those compilers, you need to
+         add the ``-std=c++11`` flag.  Otherwise, you would have to
+         install a newer compiler that supports C++11; either as a
+         binary package or through compiling from source.
 
-If you build LAMMPS with any :doc:`accelerator packages
-<Speed_packages>` included, there may be specific optimization flags
-that are either required or recommended to enable required features and
-to achieve optimal performance.  You need to include these in the
-CCFLAGS and LINKFLAGS settings above.  For details, see the individual
-package doc pages listed on the :doc:`Speed packages <Speed_packages>`
-doc page.  Or examine these files in the src/MAKE/OPTIONS directory.
-They correspond to each of the 5 accelerator packages and their hardware
-variants:
+         If you build LAMMPS with any :doc:`Speed_packages` included,
+         there may be specific compiler or linker flags that are either
+         required or recommended to enable required features and to
+         achieve optimal performance.  You need to include these in the
+         CCFLAGS and LINKFLAGS settings above.  For details, see the
+         individual package doc pages 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)
 
 ----------
 
@@ -328,51 +343,56 @@ page for more info on coupling LAMMPS to other codes.  See the
 :doc:`Python <Python_head>` doc page for more info on wrapping and
 running LAMMPS from Python via its library interface.
 
-**CMake build**\ :
+.. tabs::
 
-For CMake builds, you can select through setting CMake variables between
-building a shared or a static LAMMPS library and what kind of suffix is
-added to them (in case you want to concurrently install multiple variants
-of binaries with different settings). If none are set, defaults are applied.
+   .. tab:: CMake build
 
-.. code-block:: bash
+      For CMake builds, you can select through setting CMake variables
+      between building a shared or a static LAMMPS library and what kind
+      of suffix is added to them (in case you want to concurrently
+      install multiple variants of binaries with different settings). If
+      none are set, defaults are applied.
 
-   -D BUILD_SHARED_LIBS=value   # yes or no (default)
-   -D LAMMPS_MACHINE=name       # name = mpi, serial, mybox, titan, laptop, etc
-                                # no default value
+      .. code-block:: bash
 
-The compilation will always produce a LAMMPS library and an executable
-linked to it.  By default this will be a static library named
-``liblammps.a`` and an executable named ``lmp`` Setting
-``BUILD_SHARED_LIBS=yes`` will instead produce a shared library called
-``liblammps.so`` (or ``liblammps.dylib`` or ``liblammps.dll`` depending
-on the platform) If ``LAMMPS_MACHINE=name`` is set in addition, the name
-of the generated libraries will be changed to either
-``liblammps_name.a`` or ``liblammps_name.so``\ , respectively and the
-executable will be called ``lmp_name``.
+         -D BUILD_SHARED_LIBS=value   # yes or no (default)
+         -D LAMMPS_MACHINE=name       # name = mpi, serial, mybox, titan, laptop, etc
+                                      # no default value
 
-**Traditional make**\ :
+      The compilation will always produce a LAMMPS library and an
+      executable linked to it.  By default this will be a static library
+      named ``liblammps.a`` and an executable named ``lmp`` Setting
+      ``BUILD_SHARED_LIBS=yes`` will instead produce a shared library
+      called ``liblammps.so`` (or ``liblammps.dylib`` or
+      ``liblammps.dll`` depending on the platform) If
+      ``LAMMPS_MACHINE=name`` is set in addition, the name of the
+      generated libraries will be changed to either ``liblammps_name.a``
+      or ``liblammps_name.so``\ , respectively and the executable will
+      be called ``lmp_name``.
 
-With the traditional makefile based build process, the choice of
-the generated executable or library depends on the "mode" setting.
-Several options are available and ``mode=static`` is the default.
+   .. tab:: Traditional make
 
-.. code-block:: bash
+      With the traditional makefile based build process, the choice of
+      the generated executable or library depends on the "mode" setting.
+      Several options are available and ``mode=static`` is the default.
 
-   make machine               # build LAMMPS executable lmp_machine
-   make mode=static machine   # same as "make machine"
-   make mode=shared machine   # build LAMMPS shared lib liblammps_machine.so instead
+      .. code-block:: bash
 
-The "static" build will generate a static library called
-``liblammps_machine.a`` and an executable named ``lmp_machine``\ , while
-the "shared" build will generate a shared library
-``liblammps_machine.so`` instead and ``lmp_machine`` will be linked to
-it.  The build step will also create generic soft links, named
-``liblammps.a`` and ``liblammps.so``\ , which point to the specific
-``liblammps_machine.a/so`` files.
+         make machine               # build LAMMPS executable lmp_machine
+         make mode=static machine   # same as "make machine"
+         make mode=shared machine   # build LAMMPS shared lib liblammps_machine.so instead
 
-CMake and make info
-^^^^^^^^^^^^^^^^^^^
+      The "static" build will generate a static library called
+      ``liblammps_machine.a`` and an executable named ``lmp_machine``\ ,
+      while the "shared" build will generate a shared library
+      ``liblammps_machine.so`` instead and ``lmp_machine`` will be
+      linked to it.  The build step will also create generic soft links,
+      named ``liblammps.a`` and ``liblammps.so``\ , which point to the
+      specific ``liblammps_machine.a/so`` files.
+
+
+Additional information
+^^^^^^^^^^^^^^^^^^^^^^
 
 Note that for creating a shared library, all the libraries it depends on
 must be compiled to be compatible with shared libraries.  This should be
@@ -418,7 +438,7 @@ recommended to ensure the integrity of the system software installation.
 
 .. _debug:
 
-Excluding or removing debug support
+Including or removing debug support
 -----------------------------------
 
 By default the compilation settings will include the *-g* flag which
@@ -460,10 +480,10 @@ 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
+.. _sphinx: https://www.sphinx-doc.org
 
-Documentation make option
-^^^^^^^^^^^^^^^^^^^^^^^^^
+Documentation makefile options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The following make commands can be issued in the doc folder of the
 LAMMPS source distribution.
@@ -471,7 +491,7 @@ 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 pdf           # create 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
@@ -490,15 +510,16 @@ your system.
    current LAMMPS version (HTML and PDF files), from the website
    `download page <https://lammps.sandia.gov/download.html>`_.
 
-CMake build option
-^^^^^^^^^^^^^^^^^^
+CMake build options
+^^^^^^^^^^^^^^^^^^^
 
-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``.
+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 ``make install``.  The
+documentation build is included in the default build target, but can
+also be requested independently with ``make doc``.
 
 .. code-block:: bash
 
@@ -514,27 +535,27 @@ 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)
 
-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
 
 ----------
 
@@ -549,18 +570,19 @@ a globally visible place on your system, for others to access.  Note
 that you may need super-user privileges (e.g. sudo) if the directory
 you want to copy files to is protected.
 
-CMake build
-^^^^^^^^^^^
+.. tabs::
 
-.. code-block:: bash
+   .. tab:: CMake build
 
-   cmake -D CMAKE_INSTALL_PREFIX=path [options ...] ../cmake
-   make                        # perform make after CMake command
-   make install                # perform the installation into prefix
+      .. code-block:: bash
 
-Traditional make
-^^^^^^^^^^^^^^^^
+         cmake -D CMAKE_INSTALL_PREFIX=path [options ...] ../cmake
+         make                        # perform make after CMake command
+         make install                # perform the installation into prefix
 
-There is no "install" option in the ``src/Makefile`` for LAMMPS.  If
-you wish to do this you will need to first build LAMMPS, then manually
-copy the desired LAMMPS files to the appropriate system directories.
+   .. tab:: Traditional make
+
+      There is no "install" option in the ``src/Makefile`` for LAMMPS.
+      If you wish to do this you will need to first build LAMMPS, then
+      manually copy the desired LAMMPS files to the appropriate system
+      directories.

doc/src/Build_development.rst

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

doc/src/Build_link.rst

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

doc/src/Build_make.rst

@@ -37,7 +37,7 @@ enable (or "install") them first, as discussed on the :doc:`Build
 package <Build_package>` doc 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_package.rst

@@ -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,7 +120,8 @@ 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:`kspace_style pppm <kspace_style>` command. The
+:doc:`Screen and logfile output <Run_output>`
 doc 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,104 @@ 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).
+
+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>` 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.
 
-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.
 
 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 +290,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 +357,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 +393,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 +467,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::
 

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

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

doc/src/Commands_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/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/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.
 

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

@@ -3,7 +3,7 @@ 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
@@ -19,7 +19,7 @@ Tutorials howto
    Howto_cmake
    Howto_github
    Howto_pylammps
-   Howto_bash
+   Howto_wsl
 
 General howto
 =============

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_body.rst

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

doc/src/Howto_chunk.rst

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

doc/src/Howto_cmake.rst

@@ -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``

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
+   <pg_library>` documentation.
 
-----------
+.. spacer
 
-(3) Use LAMMPS as a library called by another code.  In this case the
-other code is the driver and calls LAMMPS as needed.  Or a wrapper
-code could link and call both LAMMPS and another code as libraries.
-Again, the :doc:`run <run>` command has options that allow it to be
-invoked with minimal overhead (no setup or clean-up) if you wish to do
-multiple short runs, driven by another program.
-
-Examples of driver codes that call LAMMPS as a library are included in
-the examples/COUPLE directory of the LAMMPS distribution; see
-examples/COUPLE/README for more details:
-
-* simple: simple driver programs in C++ and C which invoke LAMMPS as a
-  library
-* plugin: simple driver program in C which invokes LAMMPS as a plugin
-  from a shared library.
-* lammps_quest: coupling of LAMMPS and `Quest <quest_>`_, to run classical
-  MD with quantum forces calculated by a density functional code
-* lammps_spparks: coupling of LAMMPS and `SPPARKS <spparks_>`_, to couple
-  a kinetic Monte Carlo model for grain growth using MD to calculate
-  strain induced across grain boundaries
-
-.. _quest: http://dft.sandia.gov/Quest
-
-.. _spparks: http://www.sandia.gov/~sjplimp/spparks.html
-
-The :doc:`Build basics <Build_basics>` doc page describes how to build
-LAMMPS as a library.  Once this is done, you can interface with LAMMPS
-either via C++, C, Fortran, or Python (or any other language that
-supports a vanilla C-like interface).  For example, from C++ you could
-create one (or more) "instances" of LAMMPS, pass it an input script to
-process, or execute individual commands, all by invoking the correct
-class methods in LAMMPS.  From C or Fortran you can make function
-calls to do the same things.  See the :doc:`Python <Python_head>` doc
-pages for a description of the Python wrapper provided with LAMMPS
-that operates through the LAMMPS library interface.
-
-The files src/library.cpp and library.h contain the C-style interface
-to LAMMPS.  See the :doc:`Howto library <Howto_library>` doc page for a
-description of the interface and how to extend it for your needs.
-
-Note that the lammps_open() function that creates an instance of
-LAMMPS takes an MPI communicator as an argument.  This means that
-instance of LAMMPS will run on the set of processors in the
-communicator.  Thus the calling code can run LAMMPS on all or a subset
-of processors.  For example, a wrapper script might decide to
-alternate between LAMMPS and another code, allowing them both to run
-on all the processors.  Or it might allocate half the processors to
-LAMMPS and half to the other code and run both codes simultaneously
-before syncing them up periodically.  Or it might instantiate multiple
-instances of LAMMPS to perform different calculations.
-
-----------
-
-(4) Couple LAMMPS with another code in a client/server mode.  This is
-described on the :doc:`Howto client/server <Howto_client_server>` doc
-page.
+4. Couple LAMMPS with another code in a client/server mode.  This is
+   described on the :doc:`Howto client/server <Howto_client_server>` doc
+   page.

doc/src/Howto_drude.rst

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

doc/src/Howto_drude2.rst

@@ -377,7 +377,7 @@ For our phenol example, the groups would be defined as
 Note that with the fixes *drude/transform*\ , it is not required to
 specify *comm_modify vel yes* because the fixes do it anyway (several
 times and for the forces also).  To avoid the flying ice cube artifact
-:ref:`(Lamoureux) <Lamoureux2>`, where the atoms progressively freeze and the
+:ref:`(Lamoureux and Roux) <Lamoureux2>`, where the atoms progressively freeze and the
 center of mass of the whole system drifts faster and faster, the *fix
 momentum* can be used. For instance:
 
@@ -456,7 +456,7 @@ NPT ensemble using Nose-Hoover thermostat:
 
 .. _Lamoureux2:
 
-**(Lamoureux)** Lamoureux and Roux, J Chem Phys, 119, 3025-3039 (2003)
+**(Lamoureux and Roux)** Lamoureux and Roux, J Chem Phys, 119, 3025-3039 (2003)
 
 .. _Schroeder:
 

doc/src/Howto_github.rst

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

doc/src/Howto_library.rst

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

doc/src/Howto_spherical.rst

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

doc/src/Howto_thermostat.rst

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

doc/src/Howto_viscosity.rst

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

doc/src/Howto_wsl.rst

@@ -0,0 +1,359 @@
+Using LAMMPS on Windows 10 with WSL
+###################################
+
+**written by Richard Berger**
+
+----------
+
+It's always been tricky for us to have LAMMPS users and developers work on
+Windows. We primarily develop LAMMPS to run on Linux clusters. To teach
+LAMMPS in workshop settings, we had to redirect Windows users to
+Linux Virtual Machines such as VirtualBox or Unix-like compilation with
+Cygwin.
+
+With the latest updates in Windows 10 (Version 2004, Build 19041 or higher),
+Microsoft has added a new way to work on Linux-based code. The Windows
+Subsystem for Linux (WSL). With WSL Version 2, you now get a Linux Virtual
+Machine that transparently integrates into Windows. All you need is to ensure
+you have the latest Windows updates installed and enable this new feature.
+Linux VMs are then easily installed using the Microsoft Store.
+
+In this tutorial, I'll show you how to set up and compile LAMMPS for both serial
+and MPI usage in WSL2.
+
+Installation
+============
+
+Upgrade to the latest Windows 10
+--------------------------------
+
+Type "Updates" in Windows Start and select "Check for Updates".
+
+.. image:: img/wsl_tutorial/updates.png
+   :scale: 50%
+
+Install all pending updates and reboot your system as many times as
+necessary. Continue until your Windows installation is updated.
+
+.. image:: img/wsl_tutorial/windows_update.png
+   :scale: 50%
+
+Verify your system has at least **version 2004 and build 19041 or later**. You
+can find this information by clicking on "OS build info".
+
+.. image:: img/wsl_tutorial/osinfo.png
+   :scale: 50%
+
+Enable WSL
+----------
+Next, we must install two additional Windows features to enable WSL support.
+Open a PowerShell window as an administrator. Type "PowerShell" in Windows
+Start and select "Run as Administrator".
+
+.. image:: img/wsl_tutorial/powershell.png
+   :scale: 50%
+
+Windows will ask you for administrator access. After you accept a new command
+line window will appear. Type in the following command to install WSL:
+
+.. code-block::
+
+   dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
+
+.. image:: img/wsl_tutorial/wsl_install1.png
+
+Next, enable the VirtualMachinePlatform feature using the following command:
+
+.. code-block::
+
+   dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
+
+.. image:: img/wsl_tutorial/wsl_install2.png
+
+Finally, reboot your system.
+
+Update WSL kernel component
+---------------------------
+
+Download and install the :download:`WSL Kernel Component Update <https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi>`.
+Afterwards, reboot your system.
+
+Set WSL2 as default
+-------------------
+
+Again, open PowerShell as administrator and run the following command:
+
+.. code-block:: powershell
+
+   wsl --set-default-version 2
+
+This command ensures that all future Linux installations will use WSL version 2.
+
+.. image:: img/wsl_tutorial/wsl_install3.png
+
+Install a Linux Distribution
+----------------------------
+Next, we need to install a Linux distribution via the Microsoft Store.
+Install `Ubuntu 20.04 LTS <ms-windows-store://pdp/?ProductId=9n6svws3rx71>`_.
+Once installed, you can launch it like any other application from the Start
+Menu.
+
+.. image:: img/wsl_tutorial/ubuntu_in_store.png
+   :scale: 50%
+
+Initial Setup
+^^^^^^^^^^^^^
+The first time you launch the Ubuntu Linux console, it will prompt you for a
+UNIX username and password. You will need this password to perform :code:`sudo`
+commands later. Once completed, your Linux shell is ready for use. All your
+actions and commands will run as the Linux user you specified.
+
+.. image:: img/wsl_tutorial/first_login.png
+   :scale: 50%
+
+Windows Explorer / WSL integration
+==================================
+
+Your Linux installation will have its own Linux filesystem, which contains
+the Ubuntu files. Your Linux user will have a regular Linux home directory in
+:code:`/home/<USERNAME>`. This directory is different from your Windows User
+directory. Windows and Linux filesystems are connected through WSL.
+
+All hard drives in Windows are accessible in the :code:`/mnt` directory in Linux.
+E.g., WSL maps the :code:`C` hard drive to the :code:`/mnt/c` directory. That means you
+can access your Windows User directory in :code:`/mnt/c/Users/<WINDOWS_USERNAME>`.
+
+The Windows Explorer can also access the Linux filesystem. To illustrate this
+integration, open an Ubuntu console and navigate to a directory of your
+choice. To view this location in Windows Explorer, use the :code:`explorer.exe .`
+command (do not forget the final dot!).
+
+.. image:: img/wsl_tutorial/wsl_integration.png
+   :scale: 50%
+
+--------
+
+Compiling LAMMPS
+================
+
+You now have a fully functioning Ubuntu installation and can follow most
+guides to install LAMMPS on a Linux system. Here are some of the essential
+steps to follow:
+
+Install prerequisite packages
+-----------------------------
+
+Before we can begin, we need to download the necessary compiler toolchain and
+libraries to compile LAMMPS. In our Ubuntu-based Linux installation, we will
+use the :code:`apt` package manager to install additional packages.
+
+First, upgrade all existing packages using :code:`apt update` and :code:`apt upgrade`.
+
+.. code-block:: bash
+
+   sudo apt update
+   sudo apt upgrade -y
+
+Next, install the following packages with :code:`apt install`:
+
+
+.. code-block:: bash
+
+   sudo apt install -y cmake build-essential ccache gfortran openmpi-bin libopenmpi-dev \
+                       libfftw3-dev libjpeg-dev libpng-dev python3-dev python3-pip \
+                       python3-virtualenv libblas-dev liblapack-dev libhdf5-serial-dev \
+                       hdf5-tools
+
+Download LAMMPS
+---------------
+
+Obtain a copy of the LAMMPS source code and go into it using the :code:`cd` command.
+
+Option 1: Download a LAMMPS tarball using wget
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+   wget https://github.com/lammps/lammps/archive/stable_3Mar2020.tar.gz
+   tar xvzf stable_3Mar2020.tar.gz
+   cd lammps
+
+Option 2: Download a LAMMPS development version from GitHub
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: bash
+
+   git clone --depth=1 https://github.com/lammps/lammps.git
+   cd lammps
+
+
+Configure and Compile LAMMPS with CMake
+---------------------------------------
+
+A beginner-friendly way to compile LAMMPS is to use CMake. Create a :code:`build`
+directory to compile LAMMPS and move into it. This directory will store the
+build configuration and any binaries generated during compilation.
+
+.. code-block:: bash
+
+   mkdir build
+   cd build
+
+There are countless ways to compile LAMMPS. It is beyond the scope of this
+tutorial. If you want to find out more about what can be enabled, please
+consult the extensive `documentation <https://lammps.sandia.gov/doc/Build_cmake.html>`_.
+
+To compile a minimal version of LAMMPS, we're going to use a preset.
+Presets are a way to specify a collection of CMake options using a file.
+
+.. code-block:: bash
+
+   cmake ../cmake/presets/minimal.cmake ../cmake
+
+This command configures the build and generates the necessary Makefiles. To compile the binary, run the make command.
+
+.. code-block:: bash
+
+   make -j 4
+
+The :code:`-j` option specifies how many parallel processes will perform the
+compilation. This option can significantly speed up compilation times. Use a
+number that corresponds to the number of processors in your system.
+
+After the compilation completes successfully, you will have an executable
+called :code:`lmp` in the :code:`build` directory.
+
+.. image:: img/wsl_tutorial/compilation_result.png
+   :scale: 50%
+
+Please take note of the absolute path of your :code:`build` directory. You will
+need to know the location to execute the LAMMPS binary later.
+
+One way of getting the absolute path of the current directory is through the
+:code:`$PWD` variable:
+
+.. code-block:: bash
+
+   # prints out the current value of the PWD variable
+   echo $PWD
+
+Let us save this value in a temporary variable :code:`LAMMPS_BUILD_DIR` for future use:
+
+.. code-block:: bash
+
+   LAMMPS_BUILD_DIR=$PWD
+
+The full path of the LAMMPS binary then is :code:`$LAMMPS_BUILD_DIR/lmp`.
+
+------------
+
+Running an example script
+=========================
+
+Now that we have a LAMMPS binary, we will run a script from the examples folder.
+
+Switch into the :code:`examples/melt` folder:
+
+.. code-block::
+
+   cd ../examples/melt
+
+To run this example in serial, use the following command line:
+
+.. code-block::
+
+   $LAMMPS_BUILD_DIR/lmp -in in.melt
+
+To run the same script in parallel using MPI with 4 processes, do the following:
+
+.. code-block:: bash
+
+   mpirun -np 4 $LAMMPS_BUILD_DIR/lmp -in in.melt
+
+If you run LAMMPS for the first time, the Windows Firewall might prompt you
+to confirm access. LAMMPS is accessing the network stack to enable parallel
+computation. Allow the access.
+
+.. image:: img/wsl_tutorial/windows_firewall.png
+   :scale: 75%
+
+In either serial or MPI case, LAMMPS executes and will output something similar to this:
+
+.. code-block::
+
+   LAMMPS (30 Jun 2020)
+   ...
+   ...
+   ...
+   Total # of neighbors = 151513
+   Ave neighs/atom = 37.878250
+   Neighbor list builds = 12
+   Dangerous builds not checked
+   Total wall time: 0:00:00
+
+**Congratulations! You've successfully compiled and executed LAMMPS on WSL!**
+
+Final steps
+===========
+
+It is cumbersome to always specify the path of your LAMMPS binary. You can
+avoid this by adding the absolute path of your :code:`build` directory to your PATH
+environment variable.
+
+.. code-block:: bash
+
+   export PATH=$LAMMPS_BUILD_DIR:$PATH
+
+You can then run LAMMPS input scripts like this:
+
+.. code-block:: bash
+
+   lmp -in in.melt
+
+or
+
+.. code-block:: bash
+
+   mpirun -np 4 lmp -in in.melt
+
+.. note::
+
+   The value of this :code:`PATH` variable will disappear once you close your
+   console window. To persist this setting edit the :code:`$HOME/.bashrc` file using your
+   favorite text editor and add this line:
+
+   .. code-block:: bash
+
+      export PATH=/full/path/to/your/lammps/build:$PATH
+
+   **Example:**
+   If the LAMMPS executable `lmp` has the following absolute path:
+
+   .. code-block:: bash
+
+      /home/<USERNAME>/lammps/build/lmp
+
+   the :code:`PATH` variable should be:
+
+
+   .. code-block:: bash
+
+      export PATH=/home/<USERNAME>/lammps/build:$PATH
+
+   Once set up, all your Ubuntu consoles will always have access to your :code:`lmp`
+   binary without having to specify its location.
+
+Conclusion
+==========
+I hope this gives you good overview on how to start compiling and running LAMMPS on
+Windows. WSL makes preparing and running scripts on Windows a much better
+experience.
+
+If you are completely new to Linux, I highly recommend investing some time in
+studying Linux online tutorials. E.g., tutorials about Bash Shell and Basic
+Unix commands (e.g., `Linux Journey <https://linuxjourney.com/>`_). Acquiring
+these skills will make you much more productive in this environment.
+
+.. seealso::
+
+   * `Windows Subsystem for Linux Documentation <https://docs.microsoft.com/en-us/windows/wsl/>`_

doc/src/Install_git.rst

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

doc/src/Install_linux.rst

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

doc/src/Install_patch.rst

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

doc/src/Intro_features.rst

@@ -181,7 +181,7 @@ Pre- and post-processing
 
 * A handful of pre- and post-processing tools are packaged with LAMMPS,
   some of which can convert input and output files to/from formats used
-  by other codes; see the :doc:`Toos <Tools>` doc page.
+  by other codes; see the :doc:`Tools <Tools>` doc page.
 * Our group has also written and released a separate toolkit called
   `Pizza.py <pizza_>`_ which provides tools for doing setup, analysis,
   plotting, and visualization for LAMMPS simulations.  Pizza.py is
@@ -197,7 +197,7 @@ Specialized features
 ----------------------------------
 
 LAMMPS can be built with optional packages which implement a variety
-of additional capabilities.  See the :doc:`Packages <Packages>` doc
+of additional capabilities.  See the :doc:`Optional Packages <Packages>`
 page for details.
 
 These are LAMMPS capabilities which you may not think of as typical
@@ -214,7 +214,7 @@ classical MD options:
 * Monte Carlo via :doc:`GCMC <fix_gcmc>` and :doc:`tfMC <fix_tfmc>` and :doc:`atom swapping <fix_atom_swap>`
 * :doc:`path-integral molecular dynamics (PIMD) <fix_ipi>` and :doc:`this as well <fix_pimd>`
 * :doc:`Direct Simulation Monte Carlo <pair_dsmc>` for low-density fluids
-* :doc:`Peridynamics mesoscale modeling <pair_peri>`
+* :doc:`Peridynamics modeling <pair_peri>`
 * :doc:`Lattice Boltzmann fluid <fix_lb_fluid>`
 * :doc:`targeted <fix_tmd>` and :doc:`steered <fix_smd>` molecular dynamics
 * :doc:`two-temperature electron model <fix_ttm>`

doc/src/Intro_nonfeatures.rst

@@ -66,8 +66,10 @@ Here are suggestions on how to perform these tasks:
   on-the-fly via its :doc:`dump image <dump_image>` command and pass
   them to an external program, `FFmpeg <https://www.ffmpeg.org>`_ to generate
   movies from them.  For high-quality, interactive visualization there are
-  many excellent and free tools available.  See the `Other Codes page <https://lammps.sandia.gov/viz.html>`_ page of the LAMMPS website for
-  visualization packages that can use LAMMPS output data.
+  many excellent and free tools available.  See the
+  `Visualization Tools <https://lammps.sandia.gov/viz.html>`_ page of the
+  LAMMPS website for
+  visualization packages that can process LAMMPS output data.
 * **Plotting:** See the next bullet about Pizza.py as well as the
   :doc:`Python <Python_head>` doc page for examples of plotting LAMMPS
   output.  Scripts provided with the *python* tool in the tools

doc/src/Intro_overview.rst

@@ -15,7 +15,7 @@ that supports the `MPI <mpi_>`_ message-passing library.  This includes
 shared-memory boxes and distributed-memory clusters and
 supercomputers.
 
-.. _mpi: http://www-unix.mcs.anl.gov/mpi
+.. _mpi: https://en.wikipedia.org/wiki/Message_Passing_Interface
 .. _lws: https://lammps.sandia.gov
 
 LAMMPS is written in C++.  Earlier versions were written in F77 and

doc/src/Intro_website.rst

@@ -2,28 +2,27 @@ Additional website links
 ========================
 
 The `LAMMPS website <lws_>`_ has a variety of additional info about
-LAMMPS, beyond what is in this manual.  Some of the other pages in
-this Intr are included in this list.
+LAMMPS, beyond what is in this manual.  Some other useful resources
+available online are listed below.
 
 .. _lws: https://lammps.sandia.gov
 
 * `Brief intro and recently added significant features <lws_>`_
-* `List of features <https://lammps.sandia.gov/features.html>`_
-* `List of non-features <https://lammps.sandia.gov/non_features.html>`_
+* `List of features <https://lammps.sandia.gov/doc/Intro_features.html>`_
+* `List of non-features <https://lammps.sandia.gov/doc/Intro_nonfeatures.html>`_
 * `Recent bug fixes and new features <https://lammps.sandia.gov/bug.html>`_
 
 * `Download info <https://lammps.sandia.gov/download.html>`_
 * `GitHub site <https://github.com/lammps/lammps>`_
 * `SourceForge site <https://sourceforge.net/projects/lammps>`_
-* `LAMMPS open-source license <https://lammps.sandia.gov/open_source.html>`_
+* `LAMMPS open-source license <https://lammps.sandia.gov/doc/Intro_opensource.html>`_
 
-* `Glossary of MD terms relevant to LAMMPS <https://lammps.sandia.gov/glossary.html>`_
+* `Glossary of terms relevant to LAMMPS <https://lammps.sandia.gov/glossary.html>`_
 * `LAMMPS highlights with images <https://lammps.sandia.gov/pictures.html>`_
 * `LAMMPS highlights with movies <https://lammps.sandia.gov/movies.html>`_
 * `Mail list <https://lammps.sandia.gov/mail.html>`_
 * `Workshops <https://lammps.sandia.gov/workshops.html>`_
 * `Tutorials <https://lammps.sandia.gov/tutorials.html>`_
-* `Developer guide <https://lammps.sandia.gov/Developer.pdf>`_
 
 * `Pre- and post-processing tools for LAMMPS <https://lammps.sandia.gov/prepost.html>`_
 * `Other software usable with LAMMPS <https://lammps.sandia.gov/offsite.html>`_