Merge branch 'master' of github.com:lammps/lammps

.github/CODEOWNERS

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

.gitignore

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

cmake/CMakeLists.txt

@@ -90,6 +90,7 @@ if(BUILD_SHARED_LIBS) # for all pkg libs, mpi_stubs and linalg
 endif()
 
 option(BUILD_TOOLS "Build and install LAMMPS tools (msi2lmp, binary2txt, chain)" OFF)
+option(BUILD_LAMMPS_SHELL "Build and install the LAMMPS shell" OFF)
 
 include(GNUInstallDirs)
 file(GLOB ALL_SOURCES ${LAMMPS_SOURCE_DIR}/[^.]*.cpp)
@@ -343,20 +344,22 @@ find_program(GZIP_EXECUTABLE gzip)
 find_package_handle_standard_args(GZIP REQUIRED_VARS GZIP_EXECUTABLE)
 option(WITH_GZIP "Enable GZIP support" ${GZIP_FOUND})
 if(WITH_GZIP)
-  if(NOT GZIP_FOUND)
+  if(GZIP_FOUND OR ((CMAKE_SYSTEM_NAME STREQUAL Windows) AND CMAKE_CROSSCOMPILING))
+    target_compile_definitions(lammps PRIVATE -DLAMMPS_GZIP)
+  else()
     message(FATAL_ERROR "gzip executable not found")
   endif()
-  target_compile_definitions(lammps PRIVATE -DLAMMPS_GZIP)
 endif()
 
 find_program(FFMPEG_EXECUTABLE ffmpeg)
 find_package_handle_standard_args(FFMPEG REQUIRED_VARS FFMPEG_EXECUTABLE)
 option(WITH_FFMPEG "Enable FFMPEG support" ${FFMPEG_FOUND})
 if(WITH_FFMPEG)
-  if(NOT FFMPEG_FOUND)
+  if(FFMPEG_FOUND OR ((CMAKE_SYSTEM_NAME STREQUAL Windows) AND CMAKE_CROSSCOMPILING))
+    target_compile_definitions(lammps PRIVATE -DLAMMPS_FFMPEG)
+  else()
     message(FATAL_ERROR "ffmpeg executable not found")
   endif()
-  target_compile_definitions(lammps PRIVATE -DLAMMPS_FFMPEG)
 endif()
 
 if(BUILD_SHARED_LIBS)
@@ -610,36 +613,7 @@ if(BUILD_SHARED_LIBS)
 endif()
 install(FILES ${LAMMPS_DOC_DIR}/lammps.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1 RENAME ${LAMMPS_BINARY}.1)
 
-if(BUILD_TOOLS)
+include(Tools)
-  add_executable(binary2txt ${LAMMPS_TOOLS_DIR}/binary2txt.cpp)
-  target_compile_definitions(binary2txt PRIVATE -DLAMMPS_${LAMMPS_SIZES})
-  install(TARGETS binary2txt DESTINATION ${CMAKE_INSTALL_BINDIR})
-
-  include(CheckGeneratorSupport)
-  if(CMAKE_GENERATOR_SUPPORT_FORTRAN)
-    include(CheckLanguage)
-    check_language(Fortran)
-    if(CMAKE_Fortran_COMPILER)
-      enable_language(Fortran)
-      add_executable(chain.x ${LAMMPS_TOOLS_DIR}/chain.f)
-      target_link_libraries(chain.x PRIVATE ${CMAKE_Fortran_IMPLICIT_LINK_LIBRARIES})
-      install(TARGETS chain.x DESTINATION ${CMAKE_INSTALL_BINDIR})
-    else()
-      message(WARNING "No suitable Fortran compiler found, skipping building 'chain.x'")
-    endif()
-  else()
-    message(WARNING "CMake build doesn't support fortran, skipping building 'chain.x'")
-  endif()
-
-  enable_language(C)
-  get_filename_component(MSI2LMP_SOURCE_DIR ${LAMMPS_TOOLS_DIR}/msi2lmp/src ABSOLUTE)
-  file(GLOB MSI2LMP_SOURCES ${MSI2LMP_SOURCE_DIR}/[^.]*.c)
-  add_executable(msi2lmp ${MSI2LMP_SOURCES})
-  target_link_libraries(msi2lmp PRIVATE ${MATH_LIBRARIES})
-  install(TARGETS msi2lmp DESTINATION ${CMAKE_INSTALL_BINDIR})
-  install(FILES ${LAMMPS_DOC_DIR}/msi2lmp.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1)
-endif()
-
 include(Documentation)
 
 ###############################################################################
@@ -735,6 +709,7 @@ get_target_property(DEFINES lammps COMPILE_DEFINITIONS)
 include(FeatureSummary)
 feature_summary(DESCRIPTION "The following tools and libraries have been found and configured:" WHAT PACKAGES_FOUND)
 message(STATUS "<<< Build configuration >>>
+   Operating System: ${CMAKE_SYSTEM_NAME}
    Build type:       ${CMAKE_BUILD_TYPE}
    Install path:     ${CMAKE_INSTALL_PREFIX}
    Generator:        ${CMAKE_GENERATOR} using ${CMAKE_MAKE_PROGRAM}
@@ -834,3 +809,9 @@ endif()
 if(BUILD_DOC)
   message(STATUS "<<< Building HTML Manual >>>")
 endif()
+if(BUILD_TOOLS)
+  message(STATUS "<<< Building Tools >>>")
+endif()
+if(BUILD_LAMMPS_SHELL)
+  message(STATUS "<<< Building LAMMPS Shell >>>")
+endif()

cmake/Modules/Tools.cmake

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

cmake/presets/all_off.cmake

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

cmake/presets/all_on.cmake

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

cmake/presets/intel.cmake

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

doc/Makefile

@@ -65,7 +65,7 @@ DOXYFILES      = $(shell sed -n -e 's/\#.*$$//' -e '/^ *INPUT \+=/,/^[A-Z_]\+ \+
 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 "  html          create HTML pages in html dir"
 	@echo "  pdf           create Manual.pdf in this dir"
 	@echo "  fetch         fetch HTML and PDF files from LAMMPS web site"
 	@echo "  epub          create ePUB format manual for e-book readers"

doc/graphviz/lammps-invoke-python.dot

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

doc/graphviz/pylammps-invoke-lammps.dot

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

doc/graphviz/python-invoke-lammps.dot

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

doc/lammps.1

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

doc/src/Build.rst

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

doc/src/Build_basics.rst

@@ -8,7 +8,6 @@ CMake and make:
 * :ref:`Choice of compiler and compile/link options <compile>`
 * :ref:`Build the LAMMPS executable and library <exe>`
 * :ref:`Including and removing debug support <debug>`
-* :ref:`Build the LAMMPS documentation <doc>`
 * :ref:`Install LAMMPS after a build <install>`
 
 ----------
@@ -134,8 +133,8 @@ support included as well.  These are commands in the ``MPIIO``,
 ``SNAP``, ``USER-DIFFRACTION``, and ``USER-DPD`` packages.  In addition
 some packages support OpenMP threading indirectly through the libraries
 they interface to: e.g. ``LATTE``, ``KSPACE``, and ``USER-COLVARS``.
-See the :doc:`Packages details <Packages_details>` doc page for more
+See the :doc:`Packages details <Packages_details>` page for more
-info on these packages and the doc pages for their respective commands
+info on these packages and the pages for their respective commands
 for OpenMP threading info.
 
 For CMake, if you use ``BUILD_OMP=yes``, you can use these packages
@@ -159,11 +158,11 @@ 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
+because of your compiler requiring strict OpenMP 4.0 semantics, you can
 change the behavior by adding ``-D LAMMPS_OMP_COMPAT=4`` to the
 ``LMP_INC`` variable in your makefile, or add it to the command line
-while configuring with CMake. CMake will detect the suitable setting for
+while configuring with CMake.  LAMMPS will auto-detect a suitable setting
-the GNU, Clang, and Intel compilers.
+for most GNU, Clang, and Intel compilers.
 
 ----------
 
@@ -310,7 +309,7 @@ LAMMPS.
          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
+         documentation for the individual packages listed on the
          :doc:`Speed_packages` page.  Or examine these files in the
          src/MAKE/OPTIONS directory.  They correspond to each of the 5
          accelerator packages and their hardware variants:
@@ -329,6 +328,7 @@ LAMMPS.
 ----------
 
 .. _exe:
+.. _library:
 
 Build the LAMMPS executable and library
 ---------------------------------------
@@ -340,7 +340,7 @@ will then process commands provided via a file or from the console
 input.  The LAMMPS library can also be called from another application
 or a scripting language.  See the :doc:`Howto couple <Howto_couple>` doc
 page for more info on coupling LAMMPS to other codes.  See the
-:doc:`Python <Python_head>` doc page for more info on wrapping and
+:doc:`Python <Python_head>` page for more info on wrapping and
 running LAMMPS from Python via its library interface.
 
 .. tabs::
@@ -465,68 +465,6 @@ the debug information from the LAMMPS executable:
 
 ----------
 
-.. _doc:
-
-Build the LAMMPS documentation
-----------------------------------------
-
-The LAMMPS manual is written in `reStructuredText <rst_>`_ format which
-can be translated to different output format using the `Sphinx <sphinx_>`_
-document generator tool.  Currently the translation to HTML and PDF (via
-LaTeX) are supported.  For that to work a Python 3 interpreter and
-internet access is required.  For the documentation build a python
-based virtual environment is set up in the folder doc/docenv and various
-python packages are installed into that virtual environment via the pip
-tool.  The actual translation is then done via make commands.
-
-.. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html
-.. _sphinx: https://www.sphinx-doc.org
-
-Documentation makefile options
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The following make commands can be issued in the doc folder of the
-LAMMPS source distribution.
-
-.. code-block:: bash
-
-  make html          # create HTML doc pages in html directory
-  make pdf           # create Manual.pdf in this directory
-  make fetch         # fetch HTML and PDF files from LAMMPS web site
-  make clean         # remove all intermediate files
-  make clean-all     # reset the entire doc build environment
-  make anchor_check  # scan for duplicate anchor labels
-  make style_check   # check for complete and consistent style lists
-  make package_check # check for complete and consistent package lists
-  make spelling      # spell-check the manual
-
-Thus "make html" will create a "doc/html" directory with the HTML format
-manual pages so that you can browse them with a web browser locally on
-your system.
-
-.. note::
-
-   You can also download a tarball of the documentation for the
-   current LAMMPS version (HTML and PDF files), from the website
-   `download page <https://lammps.sandia.gov/download.html>`_.
-
-CMake build options
-^^^^^^^^^^^^^^^^^^^
-
-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
-
-   -D BUILD_DOC=value       # yes or no (default)
-
-----------
-
 .. _tools:
 
 Build LAMMPS tools
@@ -541,7 +479,8 @@ using CMake or Make.
 
       .. code-block:: bash
 
-         -D BUILD_TOOLS=value       # yes or no (default)
+         -D BUILD_TOOLS=value         # yes or no (default)
+         -D BUILD_LAMMPS_SHELL=value  # yes or no (default)
 
       The generated binaries will also become part of the LAMMPS installation
       (see below).
@@ -557,6 +496,9 @@ using CMake or Make.
          make micelle2d        # build only micelle2d tool
          make thermo_extract   # build only thermo_extract tool
 
+         cd lammps/tools/lammps-shell
+         make                  # build LAMMPS shell
+
 ----------
 
 .. _install:

doc/src/Build_extras.rst

@@ -18,7 +18,7 @@ in addition to
 
           $ make yes-name
 
-as described on the :doc:`Build_package <Build_package>` doc page.
+as described on the :doc:`Build_package <Build_package>` page.
 
 For a CMake build there may be additional optional or required
 variables to set.  For a build with make, a provided library under the

doc/src/Build_make.rst

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

doc/src/Build_manual.rst

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

doc/src/Build_package.rst

@@ -7,7 +7,7 @@ rigid-body constraints are in packages.  In the src directory, each
 package is a sub-directory with the package name in capital letters.
 
 An overview of packages is given on the :doc:`Packages <Packages>` doc
-page.  Brief overviews of each package are on the :doc:`Packages details <Packages_details>` doc page.
+page.  Brief overviews of each package are on the :doc:`Packages details <Packages_details>` page.
 
 When building LAMMPS, you can choose to include or exclude each
 package.  In general there is no need to include a package if you
@@ -25,7 +25,7 @@ when building that executable.
 For the majority of packages, if you follow the single step below to
 include it, you can then build LAMMPS exactly the same as you would
 without any packages installed.  A few packages may require additional
-steps, as explained on the :doc:`Build extras <Build_extras>` doc page.
+steps, as explained on the :doc:`Build extras <Build_extras>` page.
 
 These links take you to the extra instructions for those select
 packages:

doc/src/Build_settings.rst

@@ -122,7 +122,7 @@ 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:`Screen and logfile output <Run_output>`
-doc page gives more details.  A more detailed (and time consuming)
+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.
 
@@ -266,12 +266,11 @@ 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
+dimension.  See the :doc:`dump <dump>` manual page for a discussion.  If
-atom moves through the periodic box more than this limit, the value will
+an atom moves through the periodic box more than this limit, the value
-"roll over", e.g. from 511 to -512, which can cause diagnostics like the
+will "roll over", e.g. from 511 to -512, which can cause diagnostics
-mean-squared displacement, as calculated by the :doc:`compute msd
+like the mean-squared displacement, as calculated by the :doc:`compute
-<compute_msd>` command, to be faulty.
+msd <compute_msd>` command, to be faulty.
-
 
 Also note that the GPU package requires its lib/gpu library to be
 compiled with the same size setting, or the link will fail.  A CMake

doc/src/Classes.rst

@@ -5,7 +5,7 @@ LAMMPS is designed to be used as a C++ class library where one can set
 up and drive a simulation through creating a class instance and then
 calling some abstract operations or commands on that class or its member
 class instances.  These are interfaced to the :doc:`C library API
-<pg_library>`, which providing an additional level of abstraction
+<Library>`, which providing an additional level of abstraction
 simplification for common operations. The C API is also the basis for
 calling LAMMPS from Python or Fortran.
 
@@ -33,6 +33,6 @@ some selected examples for derived classes of specific models.
    :caption: Individual Base Classes
    :name: lammpsbase
 
-   pg_lammps
+   Classes_lammps
-   pg_atom
+   Classes_atom
-   pg_input
+   Classes_input

doc/src/Commands_pair.rst

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

doc/src/Developer.rst

@@ -10,8 +10,8 @@ of time and requests from the LAMMPS user community.
 .. toctree::
    :maxdepth: 1
 
-   pg_dev_org
+   Developer_org
-   pg_dev_flow
+   Developer_flow
-   pg_dev_write
+   Developer_write
-   pg_dev_utils
+   Developer_utils
-   pg_dev_classes
+   Classes

doc/src/Errors_messages.rst

@@ -3005,9 +3005,6 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
 *Dump image line requires atom style line*
    Self-explanatory.
 
-*Dump image persp option is not yet supported*
-   Self-explanatory.
-
 *Dump image requires one snapshot per file*
    Use a "\*" in the filename.
 
@@ -5108,9 +5105,6 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
    The file produced by dump image cannot be binary and must
    be for a single processor.
 
-*Invalid dump image persp value*
-   Persp value must be >= 0.0.
-
 *Invalid dump image theta value*
    Theta must be between 0.0 and 180.0 inclusive.
 
@@ -8116,9 +8110,6 @@ keyword to allow for additional bonds to be formed
 *Variable for dump image center is invalid style*
    Must be an equal-style variable.
 
-*Variable for dump image persp is invalid style*
-   Must be an equal-style variable.
-
 *Variable for dump image phi is invalid style*
    Must be an equal-style variable.
 
@@ -8259,9 +8250,6 @@ keyword to allow for additional bonds to be formed
 *Variable name for dump image center does not exist*
    Self-explanatory.
 
-*Variable name for dump image persp does not exist*
-   Self-explanatory.
-
 *Variable name for dump image phi does not exist*
    Self-explanatory.
 

doc/src/Fortran.rst

@@ -24,15 +24,24 @@ of the source files: the lammps.f90 file needs to be compiled first,
 since it provides the ``LIBLAMMPS`` module that is imported by the
 Fortran code using the interface.
 
-.. versionadded:: 30Sep2020
+.. versionadded:: 9Oct2020
 
 .. admonition:: Work in Progress
+   :class: note
 
    This Fortran module is work in progress and only the documented
    functionality is currently available. The final implementation should
    cover the entire range of functionality available in the C and
    Python library interfaces.
 
+.. note::
+
+   A contributed (and complete!) Fortran interface that is more
+   closely resembling the C-library interface is available
+   in the ``examples/COUPLE/fortran2`` folder.  Please see the
+   ``README`` file in that folder for more information about that
+   Fortran interface and how to contact its author and maintainer.
+
 ----------
 
 Creating or deleting a LAMMPS object

doc/src/Howto.rst

@@ -9,18 +9,6 @@ example input scripts included in the examples directory of the LAMMPS
 distribution and highlighted on the :doc:`Examples <Examples>` doc page
 also show how to setup and run various kinds of simulations.
 
-Tutorials howto
-===============
-
-.. toctree::
-   :name: tutorials
-   :maxdepth: 1
-
-   Howto_cmake
-   Howto_github
-   Howto_pylammps
-   Howto_wsl
-
 General howto
 =============
 
@@ -94,3 +82,16 @@ Packages howto
    Howto_drude2
    Howto_manifold
    Howto_spins
+
+Tutorials howto
+===============
+
+.. toctree::
+   :name: tutorials
+   :maxdepth: 1
+
+   Howto_cmake
+   Howto_github
+   Howto_pylammps
+   Howto_wsl
+

doc/src/Howto_cmake.rst

@@ -328,6 +328,8 @@ Some common LAMMPS specific variables
      - build LAMMPS with OpenMP support (default: ``on`` if compiler supports OpenMP fully, else ``off``)
    * - ``BUILD_TOOLS``
      - compile some additional executables from the ``tools`` folder (default: ``off``)
+   * - ``BUILD_LAMMPS_SHELL``
+     - compile the LAMMPS shell from the ``tools/lammps-shell`` folder (default: ``off``)
    * - ``BUILD_DOC``
      - include building the HTML format documentation for packaging/installing (default: ``off``)
    * - ``CMAKE_TUNE_FLAGS``

doc/src/Howto_couple.rst

@@ -54,7 +54,7 @@ context of your application.
    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.
+   <Library>` documentation.
 
 .. spacer
 

doc/src/Howto_library.rst

@@ -20,8 +20,8 @@ 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
+and is also the basis for the :doc:`Python <Python_module>` and
-:doc:`Fortran <pg_fortran>` interfaces or wrappers included in the
+:doc:`Fortran <Fortran>` interfaces or wrappers included in the
 LAMMPS source code.
 
 The ``examples/COUPLE`` and ``python/examples`` directories contain some
@@ -33,5 +33,5 @@ LAMMPS.
 
 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.
+<Library>` section of this manual.
 

doc/src/Howto_pylammps.rst

@@ -11,7 +11,7 @@ on its own or use an existing lammps Python object.  It creates a simpler,
 more "pythonic" interface to common LAMMPS functionality, in contrast to
 the ``lammps.py`` wrapper for the C-style LAMMPS library interface which
 is written using `Python ctypes <ctypes_>`_.  The ``lammps.py`` wrapper
-is discussed on the :doc:`Python library <Python_library>` doc page.
+is discussed on the :doc:`Python_head` doc page.
 
 Unlike the flat ``ctypes`` interface, PyLammps exposes a discoverable
 API.  It no longer requires knowledge of the underlying C++ code

doc/src/Install_git.rst

@@ -94,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:`Apply patch <Install_patch>` doc page,
+just as described on the :doc:`Apply patch <Install_patch>` page,
 after a patch has been installed.
 
 .. warning::

doc/src/Install_patch.rst

@@ -10,7 +10,7 @@ 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
-`bugf fixes and new feature page <https://lammps.sandia.gov/bug.html>`_
+`bug fixes and new feature page <https://lammps.sandia.gov/bug.html>`_
 of the LAMMPS website, along
 with a list of changed files and details about what is in the new patch
 release.  This page explains how to apply the patch file to your local

doc/src/Install_tarball.rst

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

doc/src/Install_windows.rst

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

doc/src/Library.rst

@@ -0,0 +1,167 @@
+LAMMPS Library Interfaces
+*************************
+
+As described on the :doc:`library interface to LAMMPS <Howto_library>`
+page, LAMMPS can be built as a library (static or shared), 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
+script <Python_head>`.  Even the LAMMPS standalone executable is
+essentially a thin wrapper on top of the LAMMPS library, creating a
+LAMMPS instance, processing input and then existing.
+
+Most of the APIs described below are based on C language wrapper
+functions in the files ``src/library.h`` and ``src/library.cpp``, but
+it is also possible to use C++ directly.  The basic procedure is
+always the same: you create one or more instances of
+:cpp:class:`LAMMPS <LAMMPS_NS::LAMMPS>`, pass commands as strings or
+from files to that LAMMPS instance to execute calculations, and/or
+call functions that read, manipulate, and update data from the active
+class instances inside LAMMPS to do analysis or perform operations
+that are not possible with existing input script commands.
+
+.. _thread-safety:
+
+.. admonition:: Thread-safety
+   :class: note
+
+   LAMMPS was initially not 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).
+
+   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.
+
+----------
+
+.. _lammps_c_api:
+
+LAMMPS C Library API
+====================
+
+The C library interface is the most commonly used path to manage LAMMPS
+instances from a compiled code and it is the basis for the :doc:`Python
+<Python_module>` and :doc:`Fortran <Fortran>` modules.  Almost all
+functions of the C language API require an argument containing a
+"handle" in the form of a ``void *`` type variable, which points to the
+location of a LAMMPS class instance.
+
+The ``library.h`` header file by default does not include the ``mpi.h``
+header file and thus hides the :cpp:func:`lammps_open` function which
+requires the declaration of the ``MPI_comm`` data type.  This is only
+a problem when the communicator that would be passed is different from
+``MPI_COMM_WORLD``.  Otherwise calling :cpp:func:`lammps_open_no_mpi`
+will work just as well.  To make :cpp:func:`lammps_open` available,
+you need to compile the code with ``-DLAMMPS_LIB_MPI`` or add the line
+``#define LAMMPS_LIB_MPI`` before ``#include "library.h"``.
+
+Please note the ``mpi.h`` file must usually be the same (and thus the
+MPI library in use) for the LAMMPS code and library and the calling code.
+The exception is when LAMMPS was compiled in serial mode using the
+``STUBS`` MPI library.  In that case the calling code may be compiled
+with a different MPI library so long as :cpp:func:`lammps_open_no_mpi`
+is called to create a LAMMPS instance.  In that case each MPI rank will
+run LAMMPS in serial mode.
+
+.. admonition:: Errors versus exceptions
+   :class: note
+
+   If the LAMMPS executable encounters an error condition, it will abort
+   after printing an error message. For a library interface this is
+   usually not desirable.  Thus LAMMPS can be compiled to to :ref:`throw
+   a C++ exception <exceptions>` instead.  If enabled, the library
+   functions will catch those exceptions and return.  The error status
+   :cpp:func:`can be queried <lammps_has_error>` and an :cpp:func:`error
+   message retrieved <lammps_get_last_error_message>`.  We thus
+   recommend enabling C++ exceptions when using the library interface,
+
+.. warning::
+
+   No checks are made on the arguments of the function calls of the C
+   library interface.  *All* function arguments must be non-NULL unless
+   *explicitly* allowed, and must point to consistent and valid data.  Buffers
+   for storing returned data must be allocated to a suitable size.
+   Passing invalid or unsuitable information will likely cause crashes
+   or corrupt data.
+
+------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   Library_create
+   Library_execute
+   Library_properties
+   Library_atoms
+   Library_objects
+   Library_scatter
+   Library_neighbor
+   Library_config
+   Library_utility
+   Library_add
+
+--------------------
+
+.. _lammps_python_api:
+
+LAMMPS Python APIs
+==================
+
+The LAMMPS Python module enables calling the LAMMPS C library API from
+Python by dynamically loading functions in the LAMMPS shared library through
+the `Python ctypes module <https://docs.python.org/3/library/ctypes.html>`_.
+Because of the dynamic loading, it is **required** that LAMMPS is compiled
+in :ref:`"shared" mode <exe>`.  The Python interface is object oriented, but
+otherwise tries to be very similar to the C library API.  Three different
+Python classes to run LAMMPS are available and they build on each other.
+More information on this is in the :doc:`Python_head`
+section of the manual.  Use of the LAMMPS Python module is described in
+:doc:`Python_module`.
+
+-------------------
+
+.. _lammps_fortran_api:
+
+LAMMPS Fortran API
+==================
+
+The LAMMPS Fortran module is a wrapper around calling functions from the
+LAMMPS C library API.  This is done using the ISO_C_BINDING feature in
+Fortran 2003.  The interface is object oriented but otherwise tries to
+be very similar to the C library API and the basic Python module.
+
+.. toctree::
+   :maxdepth: 1
+
+   Fortran
+
+-------------------
+
+.. _lammps_cplusplus_api:
+
+LAMMPS C++ API
+==============
+
+It is also possible to invoke the LAMMPS C++ API directly in your code.
+It lacks some of the convenience of the C library API, but it allows
+more direct access to simulation data and thus more low-level manipulations.
+The following links provide some examples and references to the C++ API.
+
+.. toctree::
+   :maxdepth: 1
+
+   Cplusplus
+
+

doc/src/Library_add.rst

@@ -0,0 +1,36 @@
+Extending the C API
+===================
+
+The functionality of the LAMMPS library interface has historically
+been motivated by the needs of its users.  Functions have been added
+or expanded as they were needed and used.  Contributions to the
+interface are always welcome.  However with a refactoring of the
+library interface and its documentation that started in Spring 2020,
+there are now a few requirements for including new changes or extensions.
+
+  - New functions should be orthogonal to existing ones and not
+    implement functionality that can already be achieved with the
+    existing APIs.
+  - All changes and additions should be documented with
+    `Doxygen <https://doxygen.nl>`_ style comments and references
+    to those functions added to the corresponding files in the
+    ``doc/src`` folder.
+  - If possible, new unit tests to test those new features should
+    be added.
+  - New features should also be implemented and documented not just
+    for the C interface, but also the Python and Fortran interfaces.
+  - All additions should work and be compatible with ``-DLAMMPS_BIGBIG``,
+    ``-DLAMMPS_SMALLBIG``, ``-DLAMMPS_SMALLSMALL`` as well as when
+    compiling with and without MPI support.
+  - The ``library.h`` file should be kept compatible to C code at
+    a level similar to C89. Its interfaces may not reference any
+    custom data types (e.g. ``bigint``, ``tagint``, and so on) that
+    are only known inside of LAMMPS; instead ``int`` and ``int64_t``
+    should be used.
+  - only use C style comments, not C++ style
+
+Please note that these are not **strict** requirements, but the LAMMPS
+developers very much appreciate, if they are followed and can assist
+with implementing what is missing.  It helps maintaining the code base
+and keeping it consistent.
+

doc/src/Library_atoms.rst

@@ -0,0 +1,18 @@
+Per-atom properties
+===================
+
+This section documents the following functions:
+
+- :cpp:func:`lammps_extract_atom_datatype`
+- :cpp:func:`lammps_extract_atom`
+
+-----------------------
+
+.. doxygenfunction:: lammps_extract_atom_datatype
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_extract_atom
+   :project: progguide
+

doc/src/Library_config.rst

@@ -1,18 +1,40 @@
-Retrieving LAMMPS configuration information
+Configuration information
-===========================================
+=========================
 
-The following library functions can be used to query the LAMMPS library
+This section documents the following functions:
-about compile time settings and included packages and styles.  This
+
-enables programs that use the library interface to run LAMMPS
+- :cpp:func:`lammps_version`
-simulations to determine, whether the linked LAMMPS library is compatible
+- :cpp:func:`lammps_get_os_info`
-with the requirements of the application without crashing during the
+- :cpp:func:`lammps_config_has_mpi_support`
-LAMMPS functions (e.g. due to missing pair styles from packages) or to
+- :cpp:func:`lammps_config_has_gzip_support`
-choose between different options (e.g. whether to use ``lj/cut``,
+- :cpp:func:`lammps_config_has_png_support`
-``lj/cut/opt``, ``lj/cut/omp`` or ``lj/cut/intel``).  Most of the
+- :cpp:func:`lammps_config_has_jpeg_support`
-functions can be called directly without first creating a LAMMPS
+- :cpp:func:`lammps_config_has_ffmpeg_support`
-instance.  While crashes within LAMMPS may be recovered from through
+- :cpp:func:`lammps_config_has_exceptions`
-enabling :ref:`exceptions <exceptions>`, avoiding them proactively is
+- :cpp:func:`lammps_config_has_package`
-a safer approach.
+- :cpp:func:`lammps_config_package_count`
+- :cpp:func:`lammps_config_package_name`
+- :cpp:func:`lammps_has_style`
+- :cpp:func:`lammps_style_count`
+- :cpp:func:`lammps_style_name`
+- :cpp:func:`lammps_has_id`
+- :cpp:func:`lammps_id_count`
+- :cpp:func:`lammps_id_name`
+
+--------------------
+
+These library functions can be used to query the LAMMPS library for
+compile time settings and included packages and styles.  This enables
+programs that use the library interface to determine whether the
+linked LAMMPS library is compatible with the requirements of the
+application without crashing during the LAMMPS functions (e.g. due to
+missing pair styles from packages) or to choose between different
+options (e.g. whether to use ``lj/cut``, ``lj/cut/opt``,
+``lj/cut/omp`` or ``lj/cut/intel``).  Most of the functions can be
+called directly without first creating a LAMMPS instance.  While
+crashes within LAMMPS may be recovered from by enabling
+:ref:`exceptions <exceptions>`, avoiding them proactively is a safer
+approach.
 
 .. code-block:: C
    :caption: Example for using configuration settings functions
@@ -49,6 +71,16 @@ a safer approach.
 
 -----------------------
 
+.. doxygenfunction:: lammps_version
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_get_os_info
+   :project: progguide
+
+-----------------------
+
 .. doxygenfunction:: lammps_config_has_mpi_support
    :project: progguide
 
@@ -107,3 +139,18 @@ a safer approach.
 .. doxygenfunction:: lammps_style_name
    :project: progguide
 
+-----------------------
+
+.. doxygenfunction:: lammps_has_id
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_id_count
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_id_name
+   :project: progguide
+

doc/src/Library_create.rst

@@ -0,0 +1,116 @@
+Creating or deleting a LAMMPS object
+====================================
+
+This section documents the following functions:
+
+- :cpp:func:`lammps_open`
+- :cpp:func:`lammps_open_no_mpi`
+- :cpp:func:`lammps_open_fortran`
+- :cpp:func:`lammps_close`
+- :cpp:func:`lammps_mpi_init`
+- :cpp:func:`lammps_mpi_finalize`
+- :cpp:func:`lammps_free`
+
+--------------------
+
+The :cpp:func:`lammps_open` and :cpp:func:`lammps_open_no_mpi` functions
+are used to create and initialize a :cpp:func:`LAMMPS` instance.  They
+return a reference to this instance as a ``void *`` pointer to be used
+as the "handle" argument in subsequent function calls until that
+instance is destroyed by calling :cpp:func:`lammps_close`.  Here is a
+simple example demonstrating its use:
+
+.. code-block:: C
+
+   #include "library.h"
+   #include <stdio.h>
+
+   int main(int argc, char **argv)
+   {
+     void *handle;
+     int version;
+     const char *lmpargv[] = { "liblammps", "-log", "none"};
+     int lmpargc = sizeof(lmpargv)/sizeof(const char *);
+
+     /* create LAMMPS instance */
+     handle = lammps_open_no_mpi(lmpargc, lmpargv, NULL);
+     if (handle == NULL) {
+       printf("LAMMPS initialization failed");
+       lammps_mpi_finalize();
+       return 1;
+     }
+
+     /* get and print numerical version code */
+     version = lammps_version(handle);
+     printf("LAMMPS Version: %d\n",version);
+
+     /* delete LAMMPS instance and shut down MPI */
+     lammps_close(handle);
+     lammps_mpi_finalize();
+     return 0;
+   }
+
+The LAMMPS library uses the MPI library it was compiled with and will
+either run on all processors in the ``MPI_COMM_WORLD`` communicator or
+on the set of processors in the communicator passed as the ``comm``
+argument of :cpp:func:`lammps_open`.  This means the calling code can
+run LAMMPS on all or a subset of processors.  For example, a wrapper
+code might decide to alternate between LAMMPS and another code, allowing
+them both to run on all the processors.  Or it might allocate part of
+the processors to LAMMPS and the rest to the other code by creating a
+custom communicator with ``MPI_Comm_split()`` and running both codes
+concurrently before syncing them up periodically.  Or it might
+instantiate multiple instances of LAMMPS to perform different
+calculations and either alternate between them, run them concurrently on
+split communicators, or run them one after the other.  The
+:cpp:func:`lammps_open` function may be called multiple times for this
+latter purpose.
+
+The :cpp:func:`lammps_close` function is used to shut down the
+:cpp:class:`LAMMPS <LAMMPS_NS::LAMMPS>` class pointed to by the handle
+passed as an argument and free all its memory. This has to be called
+for every instance created with one of the :cpp:func:`lammps_open`
+functions.  It will, however, **not** call ``MPI_Finalize()``, since
+that may only be called once.  See :cpp:func:`lammps_mpi_finalize` for
+an alternative to invoking ``MPI_Finalize()`` explicitly from the
+calling program.
+
+The :cpp:func:`lammps_free` function is a clean-up
+function to free memory that the library allocated previously
+via other function calls.  See below for notes in the descriptions
+of the individual commands where such memory buffers were allocated.
+
+-----------------------
+
+.. doxygenfunction:: lammps_open
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_open_no_mpi
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_open_fortran
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_close
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_mpi_init
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_mpi_finalize
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_free
+   :project: progguide

doc/src/Library_execute.rst

@@ -1,5 +1,14 @@
-Executing LAMMPS commands
+Executing commands
-=========================
+==================
+
+This section documents the following functions:
+
+- :cpp:func:`lammps_file`
+- :cpp:func:`lammps_command`
+- :cpp:func:`lammps_commands_list`
+- :cpp:func:`lammps_commands_string`
+
+--------------------
 
 Once a LAMMPS instance is created, there are multiple ways to "drive" a
 simulation.  In most cases it is easiest to process single or multiple
@@ -7,23 +16,26 @@ LAMMPS commands like in an input file.  This can be done through reading
 a file or passing single commands or lists of commands or blocks of
 commands with the following functions.
 
-Via these functions, the calling code can have the LAMMPS instance act
+Via these functions, the calling code can have LAMMPS act on a series
-on a series of :doc:`input file commands <Commands_all>` that are either
+of :doc:`input file commands <Commands_all>` that are either read from
-read from a file or passed as strings.  This for, for example, allows to
+a file or passed as strings.  For example, this allows setup of a
-setup a problem from a template file and then run it in stages while
+problem from an input script, and then running it in stages while
-performing other operations in between or concurrently.  The caller can
+performing other operations in between or concurrently.  The caller
-interleave the LAMMPS function calls with operations it performs, calls
+can interleave the LAMMPS function calls with operations it performs,
-to extract information from or set information within LAMMPS, or calls
+such as calls to extract information from or set information within
-to another code's library.
+LAMMPS, or calls to another code's library.
 
-Also equivalent to regular :doc:`input script parsing <Commands_parse>`
+Just as with :doc:`input script parsing <Commands_parse>` comments can
-is the handling of comments and expansion of variables with ``${name}``
+be included in the file or strings, and expansion of variables with
-or ``$(expression)`` syntax before the commands are parsed and
+``${name}`` or ``$(expression)`` syntax is performed.
-executed. Below is a short example using some of these functions.
+Below is a short example using some of these functions.
 
 .. code-block:: C
 
+   /* define to make the otherwise hidden prototype for "lammps_open()" visible */
+   #define LAMMPS_LIB_MPI
    #include "library.h"
+
    #include <mpi.h>
    #include <stdio.h>
 

doc/src/Library_neighbor.rst

@@ -1,8 +1,14 @@
-Accessing LAMMPS Neighbor lists
+Neighbor list access
-===============================
+====================
 
-The following functions allow to access neighbor lists
+The following functions enable access to neighbor lists generated by
-generated by LAMMPS or query their properties.
+LAMMPS or querying of their properties:
+
+- :cpp:func:`lammps_find_compute_neighlist`
+- :cpp:func:`lammps_find_fix_neighlist`
+- :cpp:func:`lammps_find_pair_neighlist`
+- :cpp:func:`lammps_neighlist_num_elements`
+- :cpp:func:`lammps_neighlist_element_neighbors`
 
 -----------------------
 

doc/src/Library_objects.rst

@@ -1,8 +1,13 @@
-Retrieving or setting properties of LAMMPS objects
+Compute, fixes, variables
-==================================================
+=========================
 
-This section documents accessing or modifying data from objects like
+This section documents accessing or modifying data stored by computes,
-computes, fixes, or variables in LAMMPS.
+fixes, or variables in LAMMPS using the following functions:
+
+- :cpp:func:`lammps_extract_compute`
+- :cpp:func:`lammps_extract_fix`
+- :cpp:func:`lammps_extract_variable`
+- :cpp:func:`lammps_set_variable`
 
 -----------------------
 

doc/src/Library_properties.rst

@@ -0,0 +1,116 @@
+System properties
+=================
+
+This section documents the following functions:
+
+- :cpp:func:`lammps_get_natoms`
+- :cpp:func:`lammps_get_thermo`
+- :cpp:func:`lammps_extract_box`
+- :cpp:func:`lammps_reset_box`
+- :cpp:func:`lammps_memory_usage`
+- :cpp:func:`lammps_get_mpi_comm`
+- :cpp:func:`lammps_extract_setting`
+- :cpp:func:`lammps_extract_global_datatype`
+- :cpp:func:`lammps_extract_global`
+
+--------------------
+
+The library interface allows extraction of different kinds of
+information about the active simulation instance and also
+modifications to it.  This enables combining of a LAMMPS simulation
+with other processing and simulation methods computed by the calling
+code, or by another code that is coupled to LAMMPS via the library
+interface.  In some cases the data returned is direct reference to the
+original data inside LAMMPS, cast to a void pointer.  In that case the
+data needs to be cast to a suitable pointer for the calling program to
+access it, and you may need to know the correct dimensions and
+lengths.  This also means you can directly change those value(s) from
+the calling program, e.g. to modify atom positions.  Of course, this
+should be done with care.  When accessing per-atom data, please note
+that this data is the per-processor **local** data and is indexed
+accordingly. Per-atom data can change sizes and ordering at every
+neighbor list rebuild or atom sort event as atoms migrate between
+sub-domains and processors.
+
+.. code-block:: C
+
+   #include "library.h"
+   #include <stdio.h>
+
+   int main(int argc, char **argv)
+   {
+     void *handle;
+     int i;
+
+     handle = lammps_open_no_mpi(0, NULL, NULL);
+     lammps_file(handle,"in.sysinit");
+     printf("Running a simulation with %g atoms.\n",
+            lammps_get_natoms(handle));
+
+     printf(" %d local and %d ghost atoms. %d atom types\n",
+            lammps_extract_setting(handle,"nlocal"),
+            lammps_extract_setting(handle,"nghost"),
+            lammps_extract_setting(handle,"ntypes"));
+
+     double  *dt = (double *)lammps_extract_global(handle,"dt");
+     printf("Changing timestep from %g to 0.5\n", *dt);
+     *dt = 0.5;
+
+     lammps_command(handle,"run 1000 post no");
+
+     for (i=0; i < 10; ++i) {
+       lammps_command(handle,"run 100 pre no post no");
+       printf("PE = %g\nKE = %g\n",
+              lammps_get_thermo(handle,"pe"),
+              lammps_get_thermo(handle,"ke"));
+     }
+     lammps_close(handle);
+     return 0;
+   }
+
+
+-----------------------
+
+.. doxygenfunction:: lammps_get_natoms
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_get_thermo
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_extract_box
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_reset_box
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_memory_usage
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_get_mpi_comm
+   :project: progguide
+
+-------------------
+
+.. doxygenfunction:: lammps_extract_setting
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_extract_global_datatype
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_extract_global
+   :project: progguide
+

doc/src/Library_scatter.rst

@@ -0,0 +1,82 @@
+Scatter/gather operations
+=========================
+
+This section has functions which gather per-atom data from one or more
+processors into a contiguous global list ordered by atom ID.  The same
+list is returned to all calling processors.  It also contains
+functions which scatter per-atom data from a contiguous global list
+across the processors that own those atom IDs.  It also has a
+create_atoms() function which can create new atoms by scattering them
+appropriately to owning processors in the LAMMPS spatial
+decomposition.
+
+It documents the following functions:
+
+- :cpp:func:`lammps_gather_atoms`
+- :cpp:func:`lammps_gather_atoms_concat`
+- :cpp:func:`lammps_gather_atoms_subset`
+- :cpp:func:`lammps_scatter_atoms`
+- :cpp:func:`lammps_scatter_atoms_subset`
+- :cpp:func:`lammps_gather`
+- :cpp:func:`lammps_gather_concat`
+- :cpp:func:`lammps_gather_subset`
+- :cpp:func:`lammps_scatter`
+- :cpp:func:`lammps_scatter_subset`
+- :cpp:func:`lammps_create_atoms`
+
+-----------------------
+
+.. doxygenfunction:: lammps_gather_atoms
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_gather_atoms_concat
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_gather_atoms_subset
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_scatter_atoms
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_scatter_atoms_subset
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_gather
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_gather_concat
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_gather_subset
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_scatter
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_scatter_subset
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_create_atoms(void *handle, int n, int *id, int *type, double *x, double *v, int *image, int bexpand)
+   :project: progguide
+
+

doc/src/Library_utility.rst

@@ -0,0 +1,60 @@
+Utility functions
+=================
+
+To simplify some tasks, the library interface contains these utility
+functions.  They do not directly call the LAMMPS library.
+
+- :cpp:func:`lammps_encode_image_flags`
+- :cpp:func:`lammps_decode_image_flags`
+- :cpp:func:`lammps_set_fix_external_callback`
+- :cpp:func:`lammps_fix_external_set_energy_global`
+- :cpp:func:`lammps_fix_external_set_virial_global`
+- :cpp:func:`lammps_is_running`
+- :cpp:func:`lammps_force_timeout`
+- :cpp:func:`lammps_has_error`
+- :cpp:func:`lammps_get_last_error_message`
+
+-----------------------
+
+.. doxygenfunction:: lammps_encode_image_flags
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_decode_image_flags(int image, int *flags)
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_set_fix_external_callback(void *, char *, FixExternalFnPtr, void*)
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_fix_external_set_energy_global
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_fix_external_set_virial_global
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_is_running
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_force_timeout
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_has_error
+   :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_get_last_error_message
+   :project: progguide

doc/src/Manual.rst

@@ -19,10 +19,10 @@ all LAMMPS development is coordinated.
 
 ----------
 
-The content for this manual is part of the LAMMPS distribution.  You
+The content for this manual is part of the LAMMPS distribution.  You can
-can build a local copy of the Manual as HTML pages or a PDF file, by
+build a local copy of the Manual as HTML pages or a PDF file, by
-following the steps on the :doc:`Manual build <Manual_build>` doc page.
+following the steps on the :doc:`Build_manual` page.  The manual is
-The manual is organized in two parts:
+organized in two parts:
 1) the :ref:`User documentation <user_documentation>` for how to install
 and use LAMMPS and 2) the :ref:`Programmer documentation <programmer_documentation>`
 for how to write programs using the LAMMPS library from different
@@ -30,8 +30,9 @@ programming languages and how to modify and extend LAMMPS.
 
 .. only:: html
 
-   Once you are familiar with LAMMPS, you may want to bookmark :doc:`this page <Commands_all>` since it gives quick access to a doc page for
+   Once you are familiar with LAMMPS, you may want to bookmark
-   every LAMMPS command.
+   :doc:`this page <Commands_all>` since it gives quick access
+   the documentation for all LAMMPS commands.
 
 .. _lws: https://lammps.sandia.gov
 
@@ -58,9 +59,7 @@ User Documentation
    Howto
    Examples
    Tools
-   Python_head
    Errors
-   Manual_build
 
 Programmer Documentation
 ************************
@@ -73,9 +72,10 @@ Programmer Documentation
    :name: progdoc
    :includehidden:
 
-   pg_library
+   Library
+   Python_head
    Modify
-   pg_developer
+   Developer
 
 .. toctree::
    :caption: Index
@@ -91,6 +91,7 @@ Programmer Documentation
    dihedrals
    impropers
    fix_modify_atc_commands
+   Bibliography
 
 Indices and tables
 ******************

doc/src/Manual_version.rst

@@ -17,7 +17,7 @@ run LAMMPS. It is also in the file src/version.h and in the LAMMPS
 directory name created when you unpack a tarball.  And it is on the
 first page of the :doc:`manual <Manual>`.
 
-* If you browse the HTML doc pages on the LAMMPS WWW site, they always
+* If you browse the HTML pages on the LAMMPS WWW site, they always
   describe the most current patch release of LAMMPS.
-* If you browse the HTML doc pages included in your tarball, they
+* If you browse the HTML pages included in your tarball, they
   describe the version you have, which may be older.

doc/src/Modify_overview.rst

@@ -56,13 +56,13 @@ the executable and can be invoked with a pair_style command like the
 example above.  Arguments like 0.1 and 3.5 can be defined and
 processed by your new class.
 
-.. note:
+.. note::
 
-  With the traditional make process, simply adding the new files to the
+   With the traditional make process, simply adding the new files to the
-  src folder and compiling LAMMPS again for the desired configuration
+   src folder and compiling LAMMPS again for the desired configuration
-  with "make machine" is sufficient.  When using CMake, you need to
+   with "make machine" is sufficient.  When using CMake, you need to
-  re-run CMake with "cmake ." in the build folder to have it recognize
+   re-run CMake with "cmake ." in the build folder to have it recognize
-  the added files and include them into the build system.
+   the added files and include them into the build system.
 
 As illustrated by this example pair style, many kinds of options are
 referred to in the LAMMPS documentation as the "style" of a particular

doc/src/Python_call.rst

@@ -1,5 +1,5 @@
-Call Python from a LAMMPS input script
+Calling Python from a LAMMPS input script
-======================================
+*****************************************
 
 LAMMPS has several commands which can be used to invoke Python
 code directly from an input script:
@@ -47,32 +47,3 @@ See the :doc:`python <python>` doc page and the :doc:`variable <variable>`
 doc page for its python-style variables for more info, including
 examples of Python code you can write for both pure Python operations
 and callbacks to LAMMPS.
-
-The :doc:`fix python/invoke <fix_python_invoke>` command can execute
-Python code at selected timesteps during a simulation run.
-
-The :doc:`pair_style python <pair_python>` command allows you to define
-pairwise potentials as python code which encodes a single pairwise
-interaction.  This is useful for rapid development and debugging of a
-new potential.
-
-To use any of these commands, you only need to build LAMMPS with the
-PYTHON package installed:
-
-.. code-block:: bash
-
-   make yes-python
-   make machine
-
-Note that this will link LAMMPS with the Python library on your
-system, which typically requires several auxiliary system libraries to
-also be linked.  The list of these libraries and the paths to find
-them are specified in the lib/python/Makefile.lammps file.  You need
-to insure that file contains the correct information for your version
-of Python and your machine to successfully build LAMMPS.  See the
-lib/python/README file for more info.
-
-If you want to write Python code with callbacks to LAMMPS, then you
-must also follow the steps summarized in the :doc:`Python run <Python_run>` doc page.  I.e. you must build LAMMPS as a shared
-library and insure that Python can find the python/lammps.py file and
-the shared library.

doc/src/Python_config.rst

@@ -0,0 +1,45 @@
+Retrieving LAMMPS configuration information
+*******************************************
+
+The following methods can be used to query the LAMMPS library
+about compile time settings and included packages and styles.
+
+.. code-block:: Python
+   :caption: Example for using configuration settings functions
+
+   from lammps import lammps
+
+   lmp = lammps()
+
+   try:
+       lmp.file("in.missing")
+   except Exception as e:
+       print("LAMMPS failed with error:", e)
+
+   # write compressed dump file depending on available of options
+
+   if lmp.has_style("dump", "atom/zstd"):
+       lmp.command("dump d1 all atom/zstd 100 dump.zst")
+   elif lmp.has_style("dump", "atom/gz"):
+       lmp.command("dump d1 all atom/gz 100 dump.gz")
+   elif lmp.has_gzip_support():
+       lmp.command("dump d1 all atom 100 dump.gz")
+   else:
+       lmp.command("dump d1 all atom 100 dump")
+
+
+-----------------------
+
+**Methods:**
+
+* :py:attr:`lammps.has_mpi_support <lammps.lammps.has_mpi_support>`
+* :py:attr:`lammps.has_exceptions <lammps.lammps.has_exceptions>`
+* :py:attr:`lammps.has_gzip_support <lammps.lammps.has_gzip_support>`
+* :py:attr:`lammps.has_png_support <lammps.lammps.has_png_support>`
+* :py:attr:`lammps.has_jpeg_support <lammps.lammps.has_jpeg_support>`
+* :py:attr:`lammps.has_ffmpeg_support <lammps.lammps.has_ffmpeg_support>`
+
+* :py:attr:`lammps.installed_packages <lammps.lammps.installed_pages>`
+
+* :py:meth:`lammps.has_style() <lammps.lammps.has_style()>`
+* :py:meth:`lammps.available_styles() <lammps.lammps.available_styles()>`

doc/src/Python_error.rst

@@ -0,0 +1,36 @@
+LAMMPS error handling in Python
+*******************************
+
+Compiling the shared library with :ref:`C++ exception support <exceptions>` provides a better error
+handling experience. Without exceptions the LAMMPS code will terminate the
+current Python process with an error message.  C++ exceptions allow capturing
+them on the C++ side and rethrowing them on the Python side. This way
+LAMMPS errors can be handled through the Python exception handling mechanism.
+
+.. code-block:: Python
+
+   from lammps import lammps, MPIAbortException
+
+   lmp = lammps()
+
+   try:
+      # LAMMPS will normally terminate itself and the running process if an error
+      # occurs. This would kill the Python interpreter. To avoid this, make sure to
+      # compile with LAMMPS_EXCEPTIONS enabled. This ensures the library API calls
+      # will not terminate the parent process. Instead, the library wrapper will
+      # detect that an error has occured and throw a Python exception
+
+      lmp.command('unknown')
+   except MPIAbortException as ae:
+      # Single MPI process got killed. This would normally be handled by an MPI abort
+      pass
+   except Exception as e:
+      # All (MPI) processes have reached this error
+      pass
+
+.. warning::
+
+   Capturing a LAMMPS exception in Python can still mean that the
+   current LAMMPS process is in an illegal state and must be terminated. It is
+   advised to save your data and terminate the Python instance as quickly as
+   possible.

doc/src/Python_examples.rst

@@ -1,6 +1,9 @@
 Example Python scripts that use LAMMPS
 ======================================
 
+The python/examples directory has Python scripts which show how Python
+can run LAMMPS, grab data, change it, and put it back into LAMMPS.
+
 These are the Python scripts included as demos in the python/examples
 directory of the LAMMPS distribution, to illustrate the kinds of
 things that are possible when Python wraps LAMMPS.  If you create your

doc/src/Python_ext.rst

@@ -0,0 +1,16 @@
+Extending the library and Python interface
+******************************************
+
+As noted above, these Python class methods correspond one-to-one with
+the functions in the LAMMPS library interface in ``src/library.cpp`` and
+``library.h``.  This means you can extend the Python wrapper via the
+following steps:
+
+* Add a new interface function to ``src/library.cpp`` and
+  ``src/library.h``.
+* Rebuild LAMMPS as a shared library.
+* Add a wrapper method to ``python/lammps.py`` for this interface
+  function.
+* You should now be able to invoke the new interface function from a
+  Python script.
+

doc/src/Python_head.rst

@@ -1,43 +1,50 @@
 Use Python with LAMMPS
 **********************
 
-These doc pages describe various ways that LAMMPS and Python can be
+These pages describe various ways that LAMMPS and Python can be used
-used together.
+together.
 
 .. toctree::
    :maxdepth: 1
 
    Python_overview
-   Python_run
-   Python_shlib
    Python_install
-   Python_mpi
+   Python_run
-   Python_test
+   Python_usage
-   Python_library
-   Python_pylammps
-   Python_examples
    Python_call
+   Python_config
+   Python_neighbor
+   Python_module
+   Python_examples
+   Python_error
+   Python_ext
+   Python_trouble
 
-If you're not familiar with `Python <http://www.python.org>`_, it's a
+If you are not familiar with `Python <http://www.python.org>`_, it is a
-powerful scripting and programming language which can do most
+powerful scripting and programming language which can do almost
-everything that lower-level languages like C or C++ can do in fewer
+everything that compiled languages like C, C++, or Fortran can do in
-lines of code.  The only drawback is slower execution speed.  Python
+fewer lines of code. It also comes with a large collection of add-on
-is also easy to use as a "glue" language to drive a program through
+modules for many purposes (either bundled or easily installed from
-its library interface, or to hook multiple pieces of software
+Python code repositories).  The major drawback is slower execution speed
-together, such as a simulation code plus a visualization tool, or to
+of the script code compared to compiled programming languages.  But when
-run a coupled multiscale or multiphysics model.
+the script code is interfaced to optimized compiled code, performance can
+be on par with a standalone executable, for as long as the scripting is
+restricted to high-level operations.  Thus Python is also convenient to
+use as a "glue" language to "drive" a program through its library
+interface, or to hook multiple pieces of software together, such as a
+simulation code and a visualization tool, or to run a coupled
+multi-scale or multi-physics model.
 
-See the :doc:`Howto_couple <Howto_couple>` doc page for more ideas about
+See the :doc:`Howto_couple` page for more ideas about coupling LAMMPS
-coupling LAMMPS to other codes.  See the :doc:`Howto library <Howto_library>` doc page for a description of the LAMMPS
+to other codes.  See the :doc:`Library` page for a description of the
-library interface provided in src/library.h and src/library.h.  That
+LAMMPS library interfaces.  That interface is exposed to Python either
-interface is exposed to Python either when calling LAMMPS from Python
+when calling LAMMPS from Python or when calling Python from a LAMMPS
-or when calling Python from a LAMMPS input script and then calling
+input script and then calling back to LAMMPS from Python code.  The
-back to LAMMPS from Python code.  The library interface is designed to
+C-library interface is designed to be easy to add functionality to,
-be easy to add functionality to.  Thus the Python interface to LAMMPS
+thus the Python interface to LAMMPS is easy to extend as well.
-is also easy to extend as well.
 
 If you create interesting Python scripts that run LAMMPS or
 interesting Python functions that can be called from a LAMMPS input
 script, that you think would be generally useful, please post them as
 a pull request to our `GitHub site <https://github.com/lammps/lammps>`_,
-and they can be added to the LAMMPS distribution or webpage.
+and they can be added to the LAMMPS distribution or web page.

doc/src/Python_install.rst

@@ -1,68 +1,468 @@
-Installing LAMMPS in Python
+Installation
-===========================
+************
 
-For Python to invoke LAMMPS, there are 2 files it needs to know about:
+The LAMMPS Python module enables calling the :ref:`LAMMPS C library API
+<lammps_c_api>` from Python by dynamically loading functions in the
+LAMMPS shared library through the Python `ctypes <ctypes_>`_
+module.  Because of the dynamic loading, it is required that LAMMPS is
+compiled in :ref:`"shared" mode <exe>`.  It is also recommended to
+compile LAMMPS with :ref:`C++ exceptions <exceptions>` enabled.
 
-* python/lammps.py
+Two files are necessary for Python to be able to invoke LAMMPS code:
-* liblammps.so or liblammps.dylib
 
-The python source code in lammps.py is the Python wrapper on the
+* The LAMMPS Python Module (``lammps.py``) from the ``python`` folder
-LAMMPS library interface. The liblammps.so or liblammps.dylib file
+* The LAMMPS Shared Library (``liblammps.so``, ``liblammps.dylib`` or
-is the shared LAMMPS library that Python loads dynamically.
+  ``liblammps.dll``) from the folder where you compiled LAMMPS.
 
-You can achieve that Python can find these files in one of two ways:
+.. _ctypes: https://docs.python.org/3/library/ctypes.html
+.. _python_virtualenv: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment
+.. _python_venv: https://docs.python.org/3/library/venv.html
+.. _python_pep405: https://www.python.org/dev/peps/pep-0405
 
-* set two environment variables pointing to the location in the source tree
+.. _python_install_guides:
-* run "make install-python" or run the python/install.py script explicitly
 
-When calling "make install-python" LAMMPS will try to install the
+Installing the LAMMPS Python Module and Shared Library
-python module and the shared library into the python site-packages folders;
+======================================================
-either the system-wide ones, or the local users ones (in case of insufficient
-permissions for the global install). Python will then find the module
-and shared library file automatically. The exact location of these folders
-depends on your python version and your operating system. When using
-the CMake build system, you can set the python executable to use during
-the CMake configuration process.  Details are given in the build instructions
-for the :ref:`PYTHON <python>` package.  When using the conventional make
-system, you can override the python version to version x.y when calling
-make with PYTHON=pythonx.y.
 
-If you set the paths to these files as environment variables, you only
+Making LAMMPS usable within Python and vice versa requires putting the
-have to do it once.  For the csh or tcsh shells, add something like
+LAMMPS Python module file (``lammps.py``) into a location where the
-this to your ~/.cshrc file, one line for each of the two files:
+Python interpreter can find it and installing the LAMMPS shared library
+into a folder that the dynamic loader searches or into the same folder
+where the ``lammps.py`` file is.  There are multiple ways to achieve
+this.
 
-.. code-block:: csh
+#. Do a full LAMMPS installation of libraries, executables, selected
+   headers, documentation (if enabled), and supporting files (only
+   available via CMake), which can also be either system-wide or into
+   user specific folders.
 
-   setenv PYTHONPATH ${PYTHONPATH}:/home/sjplimp/lammps/python
+#. Install both files into a Python ``site-packages`` folder, either
-   setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/src
+   system-wide or in the corresponding user-specific folder. This way no
+   additional environment variables need to be set, but the shared
+   library is otherwise not accessible.
 
-On MacOSX you may also need to set DYLD_LIBRARY_PATH accordingly.
+#. Do an installation into a virtual environment. This can either be
-For Bourne/Korn shells accordingly into the corresponding files using
+   an installation of the python module only or a full installation.
-the "export" shell builtin.
 
-If you use "make install-python" or the python/install.py script, you need
+#. Leave the files where they are in the source/development tree and
-to invoke it every time you rebuild LAMMPS (as a shared library) or
+   adjust some environment variables.
-make changes to the python/lammps.py file, so that the site-packages
-files are updated with the new version.
 
-If the default settings of "make install-python" are not what you want,
+.. tabs::
-you can invoke install.py from the python directory manually as
 
-.. parsed-literal::
+   .. tab:: Full install (CMake-only)
 
-   % python install.py -m \<python module\> -l <shared library> -v <version.h file> [-d \<pydir\>]
+      :ref:`Build the LAMMPS executable and library <library>` with
+      ``-DBUILD_SHARED_LIBS=on``, ``-DLAMMPS_EXCEPTIONS=on`` and
+      ``-DPKG_PYTHON=on`` (The first option is required, the other two
+      are optional by recommended).  The exact file name of the shared
+      library depends on the platform (Unix/Linux, MacOS, Windows) and
+      the build configuration being used.  The installation base folder
+      is already set by default to the ``$HOME/.local`` directory, but
+      it can be changed to a custom location defined by the
+      ``CMAKE_INSTALL_PREFIX`` CMake variable.  This uses a folder
+      called ``build`` to store files generated during compilation.
 
-* The -m flag points to the lammps.py python module file to be installed,
+      .. code-block:: bash
-* the -l flag points to the LAMMPS shared library file to be installed,
-* the -v flag points to the version.h file in the LAMMPS source
-* and the optional -d flag to a custom (legacy) installation folder
 
-If you use a legacy installation folder, you will need to set your
+         # create build folder
-PYTHONPATH and LD_LIBRARY_PATH (and/or DYLD_LIBRARY_PATH) environment
+         mkdir build
-variables accordingly, as described above.
+         cd build
+
+         # configure LAMMPS compilation
+         cmake -C cmake/presets/minimal.cmake -D BUILD_SHARED_LIBS=on \
+               -D LAMMPS_EXCEPTIONS=on -D PKG_PYTHON=on ../cmake
+
+         # compile LAMMPS
+         cmake --build .
+
+         # install LAMMPS into $HOME/.local
+         cmake --install .
+
+
+      This leads to an installation to the following locations:
+
+      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+      | File                   | Location                                                  | Notes                                                       |
+      +========================+===========================================================+=============================================================+
+      | LAMMPS Python Module   | * ``$HOME/.local/lib/pythonX.Y/site-packages/`` (32bit)   | ``X.Y`` depends on the installed Python version             |
+      |                        | * ``$HOME/.local/lib64/pythonX.Y/site-packages/`` (64bit) |                                                             |
+      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+      | LAMMPS shared library  | * ``$HOME/.local/lib/`` (32bit)                           |                                                             |
+      |                        | * ``$HOME/.local/lib64/`` (64bit)                         |                                                             |
+      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+      | LAMMPS executable      | * ``$HOME/.local/bin/``                                   |                                                             |
+      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+      | LAMMPS potential files | * ``$HOME/.local/share/lammps/potentials/``               | Set ``LAMMPS_POTENTIALS`` environment variable to this path |
+      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+
+      For a system-wide installation you need to set
+      ``CMAKE_INSTALL_PREFIX`` to a system folder like ``/usr`` (or
+      ``/usr/local``).  The installation step (**not** the
+      configuration/compilation) needs to be done with superuser
+      privilege, e.g. by using ``sudo cmake --install .``.  The
+      installation folders will then by changed to:
+
+      +------------------------+---------------------------------------------------+-------------------------------------------------------------+
+      | File                   | Location                                          | Notes                                                       |
+      +========================+===================================================+=============================================================+
+      | LAMMPS Python Module   | * ``/usr/lib/pythonX.Y/site-packages/`` (32bit)   | ``X.Y`` depends on the installed Python version             |
+      |                        | * ``/usr/lib64/pythonX.Y/site-packages/`` (64bit) |                                                             |
+      +------------------------+---------------------------------------------------+-------------------------------------------------------------+
+      | LAMMPS shared library  | * ``/usr/lib/`` (32bit)                           |                                                             |
+      |                        | * ``/usr/lib64/`` (64bit)                         |                                                             |
+      +------------------------+---------------------------------------------------+-------------------------------------------------------------+
+      | LAMMPS executable      | * ``/usr/bin/``                                   |                                                             |
+      +------------------------+---------------------------------------------------+-------------------------------------------------------------+
+      | LAMMPS potential files | * ``/usr/share/lammps/potentials/``               |                                                             |
+      +------------------------+---------------------------------------------------+-------------------------------------------------------------+
+
+      To be able to use the "user" installation you have to ensure that
+      the folder containing the LAMMPS shared library is either included
+      in a path searched by the shared linker (e.g. like
+      ``/usr/lib64/``) or part of the ``LD_LIBRARY_PATH`` environment
+      variable (or ``DYLD_LIBRARY_PATH`` on MacOS).  Otherwise you will
+      get an error when trying to create a LAMMPS object through the
+      Python module.
+
+      .. code-block:: bash
+
+         # Unix/Linux
+         export LD_LIBRARY_PATH=$HOME/.local/lib:$LD_LIBRARY_PATH
+
+         # MacOS
+         export DYLD_LIBRARY_PATH=$HOME/.local/lib:$DYLD_LIBRARY_PATH
+
+      If you plan to use the LAMMPS executable (e.g., ``lmp``), you may
+      also need to adjust the ``PATH`` environment variable (but many
+      newer Linux distributions already have ``$HOME/.local/bin``
+      included). Example:
+
+      .. code-block:: bash
+
+         export PATH=$HOME/.local/bin:$PATH
+
+      To make those changes permanent, you can add the commands to your
+      ``$HOME/.bashrc`` file.  For a system-wide installation is is not
+      necessary due to files installed in system folders that are loaded
+      automatically when a login shell is started.
+
+   .. tab:: Python module only
+
+      Compile LAMMPS with either :doc:`CMake <Build_cmake>` or the
+      :doc:`traditional make <Build_make>` procedure in :ref:`shared
+      mode <exe>`.  After compilation has finished type (in the
+      compilation folder):
+
+      .. code-block:: bash
+
+         make install-python
+
+      This will try to install (only) the shared library and the python
+      module into a system folder and if that fails (due to missing
+      write permissions) will instead do the installation to a user
+      folder under ``$HOME/.local``.  For a system-wide installation you
+      would have to gain superuser privilege, e.g. though ``sudo``
+
+      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+      | File                   | Location                                                  | Notes                                                       |
+      +========================+===========================================================+=============================================================+
+      | LAMMPS Python Module   | * ``$HOME/.local/lib/pythonX.Y/site-packages/`` (32bit)   | ``X.Y`` depends on the installed Python version             |
+      |                        | * ``$HOME/.local/lib64/pythonX.Y/site-packages/`` (64bit) |                                                             |
+      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+      | LAMMPS shared library  | * ``$HOME/.local/lib/pythonX.Y/site-packages/`` (32bit)   | ``X.Y`` depends on the installed Python version             |
+      |                        | * ``$HOME/.local/lib64/pythonX.Y/site-packages/`` (64bit) |                                                             |
+      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+
+      For a system-wide installation those folders would then become.
+
+      +------------------------+---------------------------------------------------+-------------------------------------------------------------+
+      | File                   | Location                                          | Notes                                                       |
+      +========================+===================================================+=============================================================+
+      | LAMMPS Python Module   | * ``/usr/lib/pythonX.Y/site-packages/`` (32bit)   | ``X.Y`` depends on the installed Python version             |
+      |                        | * ``/usr/lib64/pythonX.Y/site-packages/`` (64bit) |                                                             |
+      +------------------------+---------------------------------------------------+-------------------------------------------------------------+
+      | LAMMPS shared library  | * ``/usr/lib/pythonX.Y/site-packages/`` (32bit)   | ``X.Y`` depends on the installed Python version             |
+      |                        | * ``/usr/lib64/pythonX.Y/site-packages/`` (64bit) |                                                             |
+      +------------------------+---------------------------------------------------+-------------------------------------------------------------+
+
+      No environment variables need to be set for those, as those
+      folders are searched by default by Python or the LAMMPS Python
+      module.
+
+      For the traditional make process you can override the python
+      version to version x.y when calling ``make`` with
+      ``PYTHON=pythonX.Y``.  For a CMake based compilation this choice
+      has to be made during the CMake configuration step.
+
+      If the default settings of ``make install-python`` are not what you want,
+      you can invoke ``install.py`` from the python directory manually as
+
+      .. code-block:: bash
+
+         $ python install.py -m <python module> -l <shared library> -v <version.h file> [-d <pydir>]
+
+      * The ``-m`` flag points to the ``lammps.py`` python module file to be installed,
+      * the ``-l`` flag points to the LAMMPS shared library file to be installed,
+      * the ``-v`` flag points to the ``version.h`` file in the LAMMPS source
+      * and the optional ``-d`` flag to a custom (legacy) installation folder
+
+      If you use a legacy installation folder, you will need to set your
+      ``PYTHONPATH`` and ``LD_LIBRARY_PATH`` (and/or ``DYLD_LIBRARY_PATH``) environment
+      variables accordingly as explained in the description for "In place use".
+
+   .. tab:: Virtual environment
+
+      A virtual environment is a minimal Python installation inside of a
+      folder.  It allows isolating and customizing a Python environment
+      that is mostly independent from a user or system installation.
+      For the core Python environment, it uses symbolic links to the
+      system installation and thus it can be set up quickly and will not
+      take up much disk space.  This gives you the flexibility to
+      install (newer/different) versions of Python packages that would
+      potentially conflict with already installed system packages.  It
+      also does not requite any superuser privileges. See `PEP 405:
+      Python Virtual Environments <python_pep405>`_ for more
+      information.
+
+      To create a virtual environment in the folder ``$HOME/myenv``,
+      use the `venv <python_venv>`_ module as follows.
+
+      .. code-block:: bash
+
+         # create virtual environment in folder $HOME/myenv
+         python3 -m venv $HOME/myenv
+
+      For Python versions prior 3.3 you can use `virtualenv
+      <python_virtualenv>`_ command instead of "python3 -m venv".  This
+      step has to be done only once.
+
+      To activate the virtual environment type:
+
+      .. code-block:: bash
+
+         source $HOME/myenv/bin/activate
+
+      This has to be done every time you log in or open a new terminal
+      window and after you turn off the virtual environment with the
+      ``deactivate`` command.
+
+      When using CMake to build LAMMPS, you need to set
+      ``CMAKE_INSTALL_PREFIX`` to the value of the ``$VIRTUAL_ENV``
+      environment variable during the configuration step. For the
+      traditional make procedure, not additional steps are needed.
+      After compiling LAMMPS you can do a "Python module only"
+      installation with ``make install-python`` and the LAMMPS Python
+      module and the shared library file are installed into the
+      following locations:
+
+      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+      | File                   | Location                                                  | Notes                                                       |
+      +========================+===========================================================+=============================================================+
+      | LAMMPS Python Module   | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/`` (32bit)   | ``X.Y`` depends on the installed Python version             |
+      |                        | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/`` (64bit) |                                                             |
+      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+      | LAMMPS shared library  | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/`` (32bit)   | ``X.Y`` depends on the installed Python version             |
+      |                        | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/`` (64bit) |                                                             |
+      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+
+      If you do a full installation (CMake only) with "install", this
+      leads to the following installation locations:
+
+      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+      | File                   | Location                                                  | Notes                                                       |
+      +========================+===========================================================+=============================================================+
+      | LAMMPS Python Module   | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/`` (32bit)   | ``X.Y`` depends on the installed Python version             |
+      |                        | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/`` (64bit) |                                                             |
+      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+      | LAMMPS shared library  | * ``$VIRTUAL_ENV/lib/`` (32bit)                           |                                                             |
+      |                        | * ``$VIRTUAL_ENV/lib64/`` (64bit)                         |                                                             |
+      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+      | LAMMPS executable      | * ``$VIRTUAL_ENV/bin/``                                   |                                                             |
+      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+      | LAMMPS potential files | * ``$VIRTUAL_ENV/share/lammps/potentials/``               |                                                             |
+      +------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
+
+      In that case you need to modify the ``$HOME/myenv/bin/activate``
+      script in a similar fashion you need to update your
+      ``$HOME/.bashrc`` file to include the shared library and
+      executable locations in ``LD_LIBRARY_PATH`` (or
+      ``DYLD_LIBRARY_PATH`` on MacOS) and ``PATH``, respectively.
+
+      For example with:
+
+      .. code-block:: bash
+
+         # Unix/Linux
+         echo 'export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$LD_LIBRARY_PATH' >> $HOME/myenv/bin/activate
+
+         # MacOS
+         echo 'export DYLD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$LD_LIBRARY_PATH' >> $HOME/myenv/bin/activate
+
+   .. tab:: In place usage
+
+      You can also :doc:`compile LAMMPS <Build>` as usual in
+      :ref:`"shared" mode <exe>` leave the shared library and Python
+      module files inside the source/compilation folders. Instead of
+      copying the files where they can be found, you need to set the environment
+      variables ``PYTHONPATH`` (for the Python module) and
+      ``LD_LIBRARY_PATH`` (or ``DYLD_LIBRARY_PATH`` on MacOS
+
+      For Bourne shells (bash, ksh and similar) the commands are:
+
+      .. code-block:: bash
+
+         export PYTHONPATH=${PYTHONPATH}:${HOME}/lammps/python
+         export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${HOME}/lammps/src
+
+      For the C-shells like csh or tcsh the commands are:
+
+      .. code-block:: csh
+
+         setenv PYTHONPATH ${PYTHONPATH}:${HOME}/lammps/python
+         setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:${HOME}/lammps/src
+
+      On MacOS you may also need to set ``DYLD_LIBRARY_PATH`` accordingly.
+      You can make those changes permanent by editing your ``$HOME/.bashrc``
+      or ``$HOME/.login`` files, respectively.
+
+
+To verify if LAMMPS can be successfully started from Python, start the
+Python interpreter, load the ``lammps`` Python module and create a
+LAMMPS instance.  This should not generate an error message and produce
+output similar to the following:
+
+   .. code-block:: bash
+
+      $ python
+      Python 3.8.5 (default, Sep  5 2020, 10:50:12)
+      [GCC 10.2.0] on linux
+      Type "help", "copyright", "credits" or "license" for more information.
+      >>> import lammps
+      >>> lmp = lammps.lammps()
+      LAMMPS (18 Sep 2020)
+      using 1 OpenMP thread(s) per MPI task
+      >>>
+
+.. note::
+
+   Unless you opted for "In place use", you will have to rerun the installation
+   any time you recompile LAMMPS to ensure the latest Python module and shared
+   library are installed and used.
+
+.. note::
+
+   If you want Python to be able to load different versions of the
+   LAMMPS shared library with different settings, you will need to
+   manually copy the files under different names
+   (e.g. ``liblammps_mpi.so`` or ``liblammps_gpu.so``) into the
+   appropriate folder as indicated above. You can then select the
+   desired library through the *name* argument of the LAMMPS object
+   constructor (see :ref:`python_create_lammps`).
+
+.. _python_install_mpi4py:
+
+Extending Python to run in parallel
+===================================
+
+If you wish to run LAMMPS in parallel from Python, you need to extend
+your Python with an interface to MPI.  This also allows you to
+make MPI calls directly from Python in your script, if you desire.
+
+We have tested this with `MPI for Python <https://mpi4py.readthedocs.io/>`_
+(aka mpi4py) and you will find installation instruction for it below.
+
+.. note::
+
+   Older LAMMPS versions were also tested with `PyPar <https://github.com/daleroberts/pypar>`_
+   but we can no longer test it, since it does not work with the Python
+   (3.x) versions on our test servers. Since there have been no updates
+   to PyPar visible in its repository since November 2016 we have to assume
+   it is no longer maintained.
+
+Installation of mpi4py (version 3.0.3 as of Sep 2020) can be done as
+follows:
+
+- Via ``pip`` into a local user folder with:
+
+  .. code-block:: bash
+
+     pip install --user mpi4py
+
+- Via ``dnf`` into a system folder for RedHat/Fedora systems:
+
+  .. code-block:: bash
+
+     # for use with OpenMPI
+     sudo dnf install python3-mpi4py-openmpi
+     # for use with MPICH
+     sudo dnf install python3-mpi4py-openmpi
+
+- Via ``pip`` into a virtual environment (see above):
+
+  .. code-block:: bash
+
+     $ source $HOME/myenv/activate
+     (myenv)$ pip install mpi4py
+
+- Via ``pip`` into a system folder (not recommended):
+
+  .. code-block:: bash
+
+     sudo pip install mpi4py
+
+.. _mpi4py_install: https://mpi4py.readthedocs.io/en/stable/install.html
+
+For more detailed installation instructions and additional options,
+please see the `mpi4py installation <mpi4py_install>`_ page.
+
+
+To use ``mpi4py`` and LAMMPS in parallel from Python, you **must** make
+certain that **both** are using the **same** implementation and version
+of MPI library.  If you only have one MPI library installed on your
+system this is not an issue, but it can be if you have multiple MPI
+installations (e.g. on an HPC cluster to be selected through environment
+modules).  Your LAMMPS build is explicit about which MPI it is using,
+since it is either detected during CMake configuration or in the
+traditional make build system you specify the details in your low-level
+``src/MAKE/Makefile.foo`` file. The installation process of ``mpi4py``
+uses the ``mpicc`` command to find information about the MPI it uses to
+build against.  And it tries to load "libmpi.so" from the
+``LD_LIBRARY_PATH``.  This may or may not find the MPI library that
+LAMMPS is using.  If you have problems running both mpi4py and LAMMPS
+together, this is an issue you may need to address, e.g. by loading the
+module for different MPI installation so that mpi4py finds the right
+one.
+
+If you have successfully installed mpi4py, you should be able to run
+Python and type
+
+.. code-block:: python
+
+   from mpi4py import MPI
+
+without error.  You should also be able to run Python in parallel
+on a simple test script
+
+.. code-block:: bash
+
+   $ mpirun -np 4 python3 test.py
+
+where ``test.py`` contains the lines
+
+.. code-block:: python
+
+   from mpi4py import MPI
+   comm = MPI.COMM_WORLD
+   print("Proc %d out of %d procs" % (comm.Get_rank(),comm.Get_size()))
+
+and see one line of output for each processor you run on.
+
+.. code-block:: bash
+
+   # NOTE: the line order is not deterministic
+   $ mpirun -np 4 python3 test.py
+   Proc 0 out of 4 procs
+   Proc 1 out of 4 procs
+   Proc 2 out of 4 procs
+   Proc 3 out of 4 procs
 
-Note that if you want Python to be able to load different versions of
-the LAMMPS shared library (see :doc:`this section <Python_shlib>`), you will
-need to manually copy files like liblammps_g++.so into the appropriate
-system directory.  This is not needed if you set the LD_LIBRARY_PATH
-environment variable as described above.

doc/src/Python_library.rst

@@ -1,256 +0,0 @@
-Python library interface
-========================
-
-As described previously, the Python interface to LAMMPS consists of a
-Python "lammps" module, the source code for which is in
-python/lammps.py, which creates a "lammps" object, with a set of
-methods that can be invoked on that object.  The sample Python code
-below assumes you have first imported the "lammps" module in your
-Python script, as follows:
-
-.. code-block:: Python
-
-   from lammps import lammps
-
-These are the methods defined by the lammps module.  If you look at
-the files src/library.cpp and src/library.h you will see they
-correspond one-to-one with calls you can make to the LAMMPS library
-from a C++ or C or Fortran program, and which are described on the
-:doc:`Howto library <Howto_library>` doc page.
-
-The python/examples directory has Python scripts which show how Python
-can run LAMMPS, grab data, change it, and put it back into LAMMPS.
-
-.. code-block:: Python
-
-   lmp = lammps()           # create a LAMMPS object using the default liblammps.so library
-                            # 4 optional args are allowed: name, cmdargs, ptr, comm
-   lmp = lammps(ptr=lmpptr) # use lmpptr as previously created LAMMPS object
-   lmp = lammps(comm=split) # create a LAMMPS object with a custom communicator, requires mpi4py 2.0.0 or later
-   lmp = lammps(name="g++")   # create a LAMMPS object using the liblammps_g++.so library
-   lmp = lammps(name="g++",cmdargs=list)    # add LAMMPS command-line args, e.g. list = ["-echo","screen"]
-
-   lmp.close()              # destroy a LAMMPS object
-
-   version = lmp.version()  # return the numerical version id, e.g. LAMMPS 2 Sep 2015 -> 20150902
-
-   lmp.file(file)           # run an entire input script, file = "in.lj"
-   lmp.command(cmd)         # invoke a single LAMMPS command, cmd = "run 100"
-   lmp.commands_list(cmdlist)     # invoke commands in cmdlist = **"run 10", "run 20"**
-   lmp.commands_string(multicmd)  # invoke commands in multicmd = "run 10\nrun 20"
-
-   size = lmp.extract_setting(name)     # return data type info
-
-   xlo = lmp.extract_global(name,type)  # extract a global quantity
-                                        # name = "boxxlo", "nlocal", etc
-                                        # type = 0 = int
-                                        #        1 = double
-
-   boxlo,boxhi,xy,yz,xz,periodicity,box_change = lmp.extract_box()  # extract box info
-
-   coords = lmp.extract_atom(name,type)      # extract a per-atom quantity
-                                             # name = "x", "type", etc
-                                             # type = 0 = vector of ints
-                                             #        1 = array of ints
-                                             #        2 = vector of doubles
-                                             #        3 = array of doubles
-
-   eng = lmp.extract_compute(id,style,type)  # extract value(s) from a compute
-   v3 = lmp.extract_fix(id,style,type,i,j)   # extract value(s) from a fix
-                                             # id = ID of compute or fix
-                                             # style = 0 = global data
-                                             #         1 = per-atom data
-                                             #         2 = local data
-                                             # type = 0 = scalar
-                                             #        1 = vector
-                                             #        2 = array
-                                             # i,j = indices of value in global vector or array
-
-   var = lmp.extract_variable(name,group,flag)  # extract value(s) from a variable
-                                                # name = name of variable
-                                                # group = group ID (ignored for equal-style variables)
-                                                # flag = 0 = equal-style variable
-                                                #        1 = atom-style variable
-
-   value = lmp.get_thermo(name)              # return current value of a thermo keyword
-   natoms = lmp.get_natoms()                 # total # of atoms as int
-
-   flag = lmp.set_variable(name,value)       # set existing named string-style variable to value, flag = 0 if successful
-   lmp.reset_box(boxlo,boxhi,xy,yz,xz)       # reset the simulation box size
-
-   data = lmp.gather_atoms(name,type,count)  # return per-atom property of all atoms gathered into data, ordered by atom ID
-                                             # name = "x", "charge", "type", etc
-   data = lmp.gather_atoms_concat(name,type,count)  # ditto, but concatenated atom values from each proc (unordered)
-   data = lmp.gather_atoms_subset(name,type,count,ndata,ids)  # ditto, but for subset of Ndata atoms with IDs
-
-   lmp.scatter_atoms(name,type,count,data)   # scatter per-atom property to all atoms from data, ordered by atom ID
-                                             # name = "x", "charge", "type", etc
-                                             # count = # of per-atom values, 1 or 3, etc
-
-   lmp.scatter_atoms_subset(name,type,count,ndata,ids,data)  # ditto, but for subset of Ndata atoms with IDs
-
-   lmp.create_atoms(n,ids,types,x,v,image,shrinkexceed)   # create N atoms with IDs, types, x, v, and image flags
-
-----------
-
-The lines
-
-.. code-block:: Python
-
-   from lammps import lammps
-   lmp = lammps()
-
-create an instance of LAMMPS, wrapped in a Python class by the lammps
-Python module, and return an instance of the Python class as lmp.  It
-is used to make all subsequent calls to the LAMMPS library.
-
-Additional arguments to lammps() can be used to tell Python the name
-of the shared library to load or to pass arguments to the LAMMPS
-instance, the same as if LAMMPS were launched from a command-line
-prompt.
-
-If the ptr argument is set like this:
-
-.. code-block:: Python
-
-   lmp = lammps(ptr=lmpptr)
-
-then lmpptr must be an argument passed to Python via the LAMMPS
-:doc:`python <python>` command, when it is used to define a Python
-function that is invoked by the LAMMPS input script.  This mode of
-calling Python from LAMMPS is described in the :doc:`Python call <Python_call>` doc page.  The variable lmpptr refers to the
-instance of LAMMPS that called the embedded Python interpreter.  Using
-it as an argument to lammps() allows the returned Python class
-instance "lmp" to make calls to that instance of LAMMPS.  See the
-:doc:`python <python>` command doc page for examples using this syntax.
-
-Note that you can create multiple LAMMPS objects in your Python
-script, and coordinate and run multiple simulations, e.g.
-
-.. code-block:: Python
-
-   from lammps import lammps
-   lmp1 = lammps()
-   lmp2 = lammps()
-   lmp1.file("in.file1")
-   lmp2.file("in.file2")
-
-The file(), command(), commands_list(), commands_string() methods
-allow an input script, a single command, or multiple commands to be
-invoked.
-
-The extract_setting(), extract_global(), extract_box(),
-extract_atom(), extract_compute(), extract_fix(), and
-extract_variable() methods return values or pointers to data
-structures internal to LAMMPS.
-
-For extract_global() see the src/library.cpp file for the list of
-valid names.  New names could easily be added.  A double or integer is
-returned.  You need to specify the appropriate data type via the type
-argument.
-
-For extract_atom(), a pointer to internal LAMMPS atom-based data is
-returned, which you can use via normal Python subscripting.  See the
-extract() method in the src/atom.cpp file for a list of valid names.
-Again, new names could easily be added if the property you want is not
-listed.  A pointer to a vector of doubles or integers, or a pointer to
-an array of doubles (double \*\*) or integers (int \*\*) is returned.  You
-need to specify the appropriate data type via the type argument.
-
-For extract_compute() and extract_fix(), the global, per-atom, or
-local data calculated by the compute or fix can be accessed.  What is
-returned depends on whether the compute or fix calculates a scalar or
-vector or array.  For a scalar, a single double value is returned.  If
-the compute or fix calculates a vector or array, a pointer to the
-internal LAMMPS data is returned, which you can use via normal Python
-subscripting.  The one exception is that for a fix that calculates a
-global vector or array, a single double value from the vector or array
-is returned, indexed by I (vector) or I and J (array).  I,J are
-zero-based indices.  The I,J arguments can be left out if not needed.
-See the :doc:`Howto output <Howto_output>` doc page for a discussion of
-global, per-atom, and local data, and of scalar, vector, and array
-data types.  See the doc pages for individual :doc:`computes <compute>`
-and :doc:`fixes <fix>` for a description of what they calculate and
-store.
-
-For extract_variable(), an :doc:`equal-style or atom-style variable <variable>` is evaluated and its result returned.
-
-For equal-style variables a single double value is returned and the
-group argument is ignored.  For atom-style variables, a vector of
-doubles is returned, one value per atom, which you can use via normal
-Python subscripting. The values will be zero for atoms not in the
-specified group.
-
-The get_thermo() method returns the current value of a thermo
-keyword as a float.
-
-The get_natoms() method returns the total number of atoms in the
-simulation, as an int.
-
-The set_variable() method sets an existing string-style variable to a
-new string value, so that subsequent LAMMPS commands can access the
-variable.
-
-The reset_box() method resets the size and shape of the simulation
-box, e.g. as part of restoring a previously extracted and saved state
-of a simulation.
-
-The gather methods 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.
-
-Note that the data returned by the gather methods,
-e.g. gather_atoms("x"), is different from the data structure returned
-by extract_atom("x") in four ways.  (1) Gather_atoms() returns a
-vector which you index as x[i]; extract_atom() returns an array
-which you index as x[i][j].  (2) Gather_atoms() orders the atoms
-by atom ID while extract_atom() does not.  (3) Gather_atoms() returns
-a list of all atoms in the simulation; extract_atoms() returns just
-the atoms local to each processor.  (4) Finally, the gather_atoms()
-data structure is a copy of the atom coords stored internally in
-LAMMPS, whereas extract_atom() returns an array that effectively
-points directly to the internal data.  This means you can change
-values inside LAMMPS from Python by assigning a new values to the
-extract_atom() array.  To do this with the gather_atoms() vector, you
-need to change values in the vector, then invoke the scatter_atoms()
-method.
-
-For the scatter methods, the array of coordinates passed to must be a
-ctypes vector of ints or doubles, allocated and initialized something
-like this:
-
-.. code-block:: Python
-
-   from ctypes import \*
-   natoms = lmp.get_natoms()
-   n3 = 3\*natoms
-   x = (n3\*c_double)()
-   x[0] = x coord of atom with ID 1
-   x[1] = y coord of atom with ID 1
-   x[2] = z coord of atom with ID 1
-   x[3] = x coord of atom with ID 2
-   ...
-   x[n3-1] = z coord of atom with ID natoms
-   lmp.scatter_atoms("x",1,3,x)
-
-Alternatively, you can just change values in the vector returned by
-the gather methods, since they are also ctypes vectors.
-
-----------
-
-As noted above, these Python class methods correspond one-to-one with
-the functions in the LAMMPS library interface in src/library.cpp and
-library.h.  This means you can extend the Python wrapper via the
-following steps:
-
-* Add a new interface function to src/library.cpp and
-  src/library.h.
-* Rebuild LAMMPS as a shared library.
-* Add a wrapper method to python/lammps.py for this interface
-  function.
-* You should now be able to invoke the new interface function from a
-  Python script.
-

doc/src/Python_module.rst

@@ -0,0 +1,158 @@
+The ``lammps`` Python module
+****************************
+
+.. py:module:: lammps
+
+The LAMMPS Python interface is implemented as a module called
+:py:mod:`lammps` in the ``lammps.py`` file in the ``python`` folder of
+the LAMMPS source code distribution.  After compilation of LAMMPS, the
+module can be installed into a Python system folder or a user folder
+with ``make install-python``.  Components of the module can then loaded
+into a Python session with the ``import`` command.
+
+There are multiple Python interface classes in the :py:mod:`lammps` module:
+
+- the :py:class:`lammps <lammps.lammps>` class. This is a wrapper around
+  the C-library interface and its member functions try to replicate the
+  :ref:`C-library API <lammps_c_api>` closely.  This is the most
+  feature-complete Python API.
+- the :py:class:`PyLammps <lammps.PyLammps>` class. This is a more high-level
+  and more Python style class implemented on top of the
+  :py:class:`lammps <lammps.lammps>` class.
+- the :py:class:`IPyLammps <lammps.IPyLammps>` class is derived from
+  :py:class:`PyLammps <lammps.PyLammps>` and adds embedded graphics
+  features to conveniently include LAMMPS into `Jupyter
+  <https://jupyter.org/>`_ notebooks.
+
+.. _mpi4py_url: https://mpi4py.readthedocs.io
+
+----------
+
+The ``lammps`` class API
+========================
+
+The :py:class:`lammps <lammps.lammps>` class is the core of the LAMMPS
+Python interfaces.  It is a wrapper around the :ref:`LAMMPS C library
+API <lammps_c_api>` using the `Python ctypes module
+<https://docs.python.org/3/library/ctypes.html>`_ and a shared library
+compiled from the LAMMPS sources code.  The individual methods in this
+class try to closely follow the corresponding C functions.  The handle
+argument that needs to be passed to the C functions is stored internally
+in the class and automatically added when calling the C library
+functions. Below is a detailed documentation of the API.
+
+.. autoclass:: lammps.lammps
+   :members:
+
+.. autoclass:: lammps.numpy_wrapper
+   :members:
+
+----------
+
+The ``PyLammps`` class API
+==========================
+
+The :py:class:`PyLammps <lammps.PyLammps>` class is a wrapper that creates a
+simpler, more "Pythonic" interface to common LAMMPS functionality. LAMMPS
+data structures are exposed through objects and properties. This makes Python
+scripts shorter and more concise. See the :doc:`PyLammps Tutorial
+<Howto_pylammps>` for an introduction on how to use this interface.
+
+.. autoclass:: lammps.PyLammps
+   :members:
+
+.. autoclass:: lammps.AtomList
+   :members:
+
+.. autoclass:: lammps.Atom
+   :members:
+
+.. autoclass:: lammps.Atom2D
+   :members:
+
+----------
+
+The ``IPyLammps`` class API
+===========================
+
+The :py:class:`IPyLammps <lammps.PyLammps>` class is an extension of
+:py:class:`PyLammps <lammps.PyLammps>`, adding additional functions to
+quickly display visualizations such as images and videos inside of IPython.
+See the :doc:`PyLammps Tutorial <Howto_pylammps>` for examples.
+
+.. autoclass:: lammps.IPyLammps
+   :members:
+
+----------
+
+Additional components of the ``lammps`` module
+==============================================
+
+The :py:mod:`lammps` module additionally contains several constants
+and the :py:class:`NeighList <lammps.NeighList>` class:
+
+.. _py_datatype_constants:
+
+Data Types
+----------
+
+.. py:data:: LAMMPS_INT, LAMMPS_INT_2D, LAMMPS_DOUBLE, LAMMPS_DOUBLE_2D, LAMMPS_INT64, LAMMPS_INT64_2D, LAMMPS_STRING
+   :type: int
+
+   Constants in the :py:mod:`lammps` module to indicate how to
+   cast data when the C library function returns a void pointer.
+   Used in :py:func:`lammps.extract_global` and :py:func:`lammps.extract_atom`.
+   See :cpp:enum:`_LMP_DATATYPE_CONST` for the equivalent constants in the
+   C library interface.
+
+.. _py_style_constants:
+
+Style Constants
+---------------
+
+.. py:data:: LMP_STYLE_GLOBAL, LMP_STYLE_ATOM, LMP_STYLE_LOCAL
+   :type: int
+
+   Constants in the :py:mod:`lammps` module to select what style of data
+   to request from computes or fixes. See :cpp:enum:`_LMP_STYLE_CONST`
+   for the equivalent constants in the C library interface. Used in
+   :py:func:`lammps.extract_compute`, :py:func:`lammps.extract_fix`, and their NumPy variants
+   :py:func:`lammps.numpy.extract_compute() <numpy_wrapper.extract_compute>` and
+   :py:func:`lammps.numpy.extract_fix() <numpy_wrapper.extract_fix>`.
+
+.. _py_type_constants:
+
+Type Constants
+--------------
+
+.. py:data:: LMP_TYPE_SCALAR, LMP_TYLE_VECTOR, LMP_TYPE_ARRAY, LMP_SIZE_VECTOR, LMP_SIZE_ROWS, LMP_SIZE_COLS
+   :type: int
+
+   Constants in the :py:mod:`lammps` module to select what type of data
+   to request  from computes  or fixes.  See :cpp:enum:`_LMP_TYPE_CONST`
+   for the equivalent constants in the C library interface. Used in
+   :py:func:`lammps.extract_compute`, :py:func:`lammps.extract_fix`, and their NumPy variants
+   :py:func:`lammps.numpy.extract_compute() <numpy_wrapper.extract_compute>` and
+   :py:func:`lammps.numpy.extract_fix() <numpy_wrapper.extract_fix>`.
+
+.. _py_vartype_constants:
+
+Variable Type Constants
+------------------------
+
+.. py:data:: LMP_VAR_EQUAL, LMP_VAR_ATOM
+   :type: int
+
+   Constants in the :py:mod:`lammps` module to select what type of
+   variable to query when calling :py:func:`lammps.extract_variable`. See also: :doc:`variable command <variable>`.
+
+Classes representing internal objects
+-------------------------------------
+
+.. autoclass:: lammps.NeighList
+   :members:
+   :no-undoc-members:
+
+.. autoclass:: lammps.NumPyNeighList
+   :members:
+   :no-undoc-members:

doc/src/Python_mpi.rst

@@ -1,71 +0,0 @@
-Extending Python to run in parallel
-===================================
-
-If you wish to run LAMMPS in parallel from Python, you need to extend
-your Python with an interface to MPI.  This also allows you to
-make MPI calls directly from Python in your script, if you desire.
-
-We have tested this with mpi4py and pypar:
-
-* `MPI for Python <https://mpi4py.readthedocs.io/>`_
-* `pypar <https://github.com/daleroberts/pypar>`_
-
-We recommend the use of mpi4py as it is the more complete MPI interface,
-and as of version 2.0.0 mpi4py allows passing a custom MPI communicator
-to the LAMMPS constructor, which means one can easily run one or more
-LAMMPS instances on subsets of the total MPI ranks.
-
-To install mpi4py (version mpi4py-3.0.3 as of Nov 2019), unpack it
-and from its main directory, type
-
-.. code-block:: bash
-
-   python setup.py build
-   sudo python setup.py install
-
-Again, the "sudo" is only needed if required to copy mpi4py files into
-your Python distribution's site-packages directory. To install with
-user privilege into the user local directory type
-
-.. code-block:: bash
-
-   python setup.py install --user
-
-If you have successfully installed mpi4py, you should be able to run
-Python and type
-
-.. code-block:: python
-
-   from mpi4py import MPI
-
-without error.  You should also be able to run python in parallel
-on a simple test script
-
-.. code-block:: bash
-
-   % mpirun -np 4 python test.py
-
-where test.py contains the lines
-
-.. code-block:: python
-
-   from mpi4py import MPI
-   comm = MPI.COMM_WORLD
-   print "Proc %d out of %d procs" % (comm.Get_rank(),comm.Get_size())
-
-and see one line of output for each processor you run on.
-
-.. note::
-
-   To use mpi4py and LAMMPS in parallel from Python, you must
-   insure both are using the same version of MPI.  If you only have one
-   MPI installed on your system, this is not an issue, but it can be if
-   you have multiple MPIs.  Your LAMMPS build is explicit about which MPI
-   it is using, since you specify the details in your low-level
-   src/MAKE/Makefile.foo file.  Mpi4py uses the "mpicc" command to find
-   information about the MPI it uses to build against.  And it tries to
-   load "libmpi.so" from the LD_LIBRARY_PATH.  This may or may not find
-   the MPI library that LAMMPS is using.  If you have problems running
-   both mpi4py and LAMMPS together, this is an issue you may need to
-   address, e.g. by moving other MPI installations so that mpi4py finds
-   the right one.

doc/src/Python_neighbor.rst

@@ -0,0 +1,18 @@
+Accessing LAMMPS Neighbor lists
+*******************************
+
+**Methods:**
+
+* :py:meth:`lammps.get_neighlist() <lammps.lammps.get_neighlist()>`: Get neighbor list for given index
+* :py:meth:`lammps.get_neighlist_size()`: Get number of elements in neighbor list
+* :py:meth:`lammps.get_neighlist_element_neighbors()`: Get element in neighbor list and its neighbors
+
+* :py:meth:`lammps.find_pair_neighlist() <lammps.lammps.find_pair_neighlist()>`: Find neighbor list of pair style
+* :py:meth:`lammps.find_fix_neighlist() <lammps.lammps.find_pair_neighlist()>`: Find neighbor list of pair style
+* :py:meth:`lammps.find_compute_neighlist() <lammps.lammps.find_pair_neighlist()>`: Find neighbor list of pair style
+
+
+**NumPy Methods:**
+
+* :py:meth:`lammps.numpy.get_neighlist() <lammps.numpy_wrapper.get_neighlist()>`: Get neighbor list for given index, which uses NumPy arrays for its element neighbor arrays
+* :py:meth:`lammps.numpy.get_neighlist_element_neighbors() <lammps.numpy_wrapper.get_neighlist_element_neighbors()>`: Get element in neighbor list and its neighbors (as numpy array)

doc/src/Python_overview.rst

@@ -1,25 +1,93 @@
-Overview of Python and LAMMPS
+Overview
-=============================
+========
+
+The LAMMPS distribution includes a ``python`` directory with the Python
+code needed to run LAMMPS from Python.  The ``python/lammps.py``
+contains :doc:`the "lammps" Python <Python_module>` that wraps the
+LAMMPS C-library interface.  This file makes it is possible to do the
+following either from a Python script, or interactively from a Python
+prompt:
+
+- create one or more instances of LAMMPS
+- invoke LAMMPS commands or read them from an input script
+- run LAMMPS incrementally
+- extract LAMMPS results
+- and modify internal LAMMPS data structures.
+
+From a Python script you can do this in serial or in parallel.  Running
+Python interactively in parallel does not generally work, unless you
+have a version of Python that extends Python to enable multiple
+instances of Python to read what you type.
+
+To do all of this, you must build LAMMPS in :ref:`"shared" mode <exe>`
+and make certain that your Python interpreter can find the ``lammps.py``
+file and the LAMMPS shared library file.
+
+.. _ctypes: https://docs.python.org/3/library/ctypes.html
+
+The Python wrapper for LAMMPS uses the `ctypes <ctypes_>`_ package in
+Python, which auto-generates the interface code needed between Python
+and a set of C-style library functions.  Ctypes has been part of the
+standard Python distribution since version 2.5.  You can check which
+version of Python you have by simply typing "python" at a shell prompt.
+Below is an example output for Python version 3.8.5.
+
+.. code-block::
+
+   $ python
+   Python 3.8.5 (default, Aug 12 2020, 00:00:00)
+   [GCC 10.2.1 20200723 (Red Hat 10.2.1-1)] on linux
+   Type "help", "copyright", "credits" or "license" for more information.
+   >>>
+
+
+.. warning:: Python 2 support is deprecated
+
+   While the LAMMPS Python module was originally developed to support
+   both, Python 2 and 3, any new code is only tested with Python 3.
+   Please note that Python 2 is no longer maintained as of `January 1,
+   2020 <https://www.python.org/doc/sunset-python-2/>`_.  Therefore, we
+   highly recommend using Python version 3.6 or later.  Compatibility to
+   Python 2 will be removed eventually.
+
+---------
 
 LAMMPS can work together with Python in three ways.  First, Python can
-wrap LAMMPS through the its :doc:`library interface <Howto_library>`, so
+wrap LAMMPS through the its :doc:`library interface <Library>`, so
 that a Python script can create one or more instances of LAMMPS and
-launch one or more simulations.  In Python lingo, this is called
+launch one or more simulations.  In Python terms, this is referred to as
 "extending" Python with a LAMMPS module.
 
-Second, a lower-level Python interface can be used indirectly through
+.. figure:: JPG/python-invoke-lammps.png
-the provided PyLammps and IPyLammps wrapper classes, written in Python.
+   :figclass: align-center
-These wrappers try to simplify the usage of LAMMPS in Python by
-providing an object-based interface to common LAMMPS functionality.
-They also reduces the amount of code necessary to parameterize LAMMPS
-scripts through Python and make variables and computes directly
-accessible.
 
-Third, LAMMPS can use the Python interpreter, so that a LAMMPS
+   Launching LAMMPS via Python
-input script or styles can invoke Python code directly, and pass
+
-information back-and-forth between the input script and Python
+
-functions you write.  This Python code can also callback to LAMMPS
+Second, the lower-level Python interface in the :py:class:`lammps Python
-to query or change its attributes through the LAMMPS Python module
+class <lammps.lammps>` can be used indirectly through the provided
-mentioned above.  In Python lingo, this is "embedding" Python in
+:py:class:`PyLammps <lammps.PyLammps>` and :py:class:`IPyLammps
-LAMMPS.  When used in this mode, Python can perform script operations
+<lammps.IPyLammps>` wrapper classes, also written in Python.  These
-that the simple LAMMPS input script syntax can not.
+wrappers try to simplify the usage of LAMMPS in Python by providing a
+more object-based interface to common LAMMPS functionality.  They also
+reduce the amount of code necessary to parameterize LAMMPS scripts
+through Python and make variables and computes directly accessible.
+
+.. figure:: JPG/pylammps-invoke-lammps.png
+   :figclass: align-center
+
+   Using the PyLammps / IPyLammps wrappers
+
+Third, LAMMPS can use the Python interpreter, so that a LAMMPS input
+script or styles can invoke Python code directly, and pass information
+back-and-forth between the input script and Python functions you write.
+This Python code can also call back to LAMMPS to query or change its
+attributes through the LAMMPS Python module mentioned above.  In Python
+terms, this is called "embedding" Python into LAMMPS.  When used in this
+mode, Python can perform script operations that the simple LAMMPS input
+script syntax can not.
+
+.. figure:: JPG/lammps-invoke-python.png
+   :figclass: align-center
+
+   Calling Python code from LAMMPS

doc/src/Python_pylammps.rst

@@ -1,5 +0,0 @@
-PyLammps interface
-==================
-
-PyLammps is a Python wrapper class which can be created on its own or
-use an existing lammps Python object.  It has its own :doc:`Howto pylammps <Howto_pylammps>` doc page.

doc/src/Python_run.rst

@@ -1,32 +1,110 @@
 Run LAMMPS from Python
 ======================
 
-The LAMMPS distribution includes a python directory with all you need
+Running LAMMPS and Python in serial:
-to run LAMMPS from Python.  The python/lammps.py file wraps the LAMMPS
+-------------------------------------
-library interface, with one wrapper function per LAMMPS library
-function.  This file makes it is possible to do the following either
-from a Python script, or interactively from a Python prompt: create
-one or more instances of LAMMPS, invoke LAMMPS commands or give it an
-input script, run LAMMPS incrementally, extract LAMMPS results, an
-modify internal LAMMPS variables.  From a Python script you can do
-this in serial or parallel.  Running Python interactively in parallel
-does not generally work, unless you have a version of Python that
-extends Python to enable multiple instances of Python to read what you
-type.
 
-To do all of this, you must first build LAMMPS as a shared library,
+To run a LAMMPS in serial, type these lines into Python
-then insure that your Python can find the python/lammps.py file and
+interactively from the ``bench`` directory:
-the shared library.
 
-Two advantages of using Python to run LAMMPS are how concise the
+.. code-block:: python
-language is, and that it can be run interactively, enabling rapid
-development and debugging.  If you use it to mostly invoke costly
-operations within LAMMPS, such as running a simulation for a
-reasonable number of timesteps, then the overhead cost of invoking
-LAMMPS through Python will be negligible.
 
-The Python wrapper for LAMMPS uses the "ctypes" package in Python,
+   >>> from lammps import lammps
-which auto-generates the interface code needed between Python and a
+   >>> lmp = lammps()
-set of C-style library functions.  Ctypes is part of standard Python
+   >>> lmp.file("in.lj")
-for versions 2.5 and later.  You can check which version of Python you
+
-have by simply typing "python" at a shell prompt.
+Or put the same lines in the file ``test.py`` and run it as
+
+.. code-block:: bash
+
+   $ python3 test.py
+
+Either way, you should see the results of running the ``in.lj`` benchmark
+on a single processor appear on the screen, the same as if you had
+typed something like:
+
+.. code-block:: bash
+
+   lmp_serial -in in.lj
+
+Running LAMMPS and Python in parallel with MPI
+----------------------------------------------
+
+To run LAMMPS in parallel, assuming you have installed the
+`mpi4py <https://mpi4py.readthedocs.io>`_ package as discussed
+:ref:`python_install_mpi4py`, create a ``test.py`` file containing these lines:
+
+.. code-block:: python
+
+   from mpi4py import MPI
+   from lammps import lammps
+   lmp = lammps()
+   lmp.file("in.lj")
+   me = MPI.COMM_WORLD.Get_rank()
+   nprocs = MPI.COMM_WORLD.Get_size()
+   print("Proc %d out of %d procs has" % (me,nprocs),lmp)
+   MPI.Finalize()
+
+You can run the script in parallel as:
+
+.. code-block:: bash
+
+   $ mpirun -np 4 python3 test.py
+
+and you should see the same output as if you had typed
+
+.. code-block:: bash
+
+   $ mpirun -np 4 lmp_mpi -in in.lj
+
+Note that without the mpi4py specific lines from ``test.py``
+
+.. code-block::
+
+   from lammps import lammps
+   lmp = lammps()
+   lmp.file("in.lj")
+
+running the script with ``mpirun`` on :math:`P` processors would lead to
+:math:`P` independent simulations to run parallel, each with a single
+processor. Therefore, if you use the mpi4py lines and you see multiple LAMMPS
+single processor outputs, mpi4py is not working correctly.
+
+Also note that once you import the mpi4py module, mpi4py initializes MPI
+for you, and you can use MPI calls directly in your Python script, as
+described in the mpi4py documentation.  The last line of your Python
+script should be ``MPI.finalize()``, to insure MPI is shut down
+correctly.
+
+Running Python scripts
+----------------------
+
+Note that any Python script (not just for LAMMPS) can be invoked in
+one of several ways:
+
+.. code-block:: bash
+
+   $ python script.py
+   $ python -i script.py
+   $ ./script.py
+
+The last command requires that the first line of the script be
+something like this:
+
+.. code-block:: bash
+
+   #!/usr/bin/python
+   #!/usr/bin/python -i
+
+where the path points to where you have Python installed, and that you
+have made the script file executable:
+
+.. code-block:: bash
+
+   $ chmod +x script.py
+
+Without the ``-i`` flag, Python will exit when the script finishes.
+With the ``-i`` flag, you will be left in the Python interpreter when
+the script finishes, so you can type subsequent commands.  As
+mentioned above, you can only run Python interactively when running
+Python on a single processor, not in parallel.

doc/src/Python_shlib.rst

@@ -1,78 +0,0 @@
-Build LAMMPS as a shared library
-================================
-
-.. TODO this is mostly redundant and should be addressed in the 'progguide' branch if it has not already
-
-Build LAMMPS as a shared library using make
--------------------------------------------
-
-Instructions on how to build LAMMPS as a shared library are given on
-the :doc:`Build_basics <Build_basics>` doc page.  A shared library is
-one that is dynamically loadable, which is what Python requires to
-wrap LAMMPS.  On Linux this is a library file that ends in ".so", not
-".a".
-
-From the src directory, type
-
-.. code-block:: bash
-
-   make foo mode=shared
-
-where foo is the machine target name, such as mpi or serial.
-This should create the file liblammps_foo.so in the src directory, as
-well as a soft link liblammps.so, which is what the Python wrapper will
-load by default.  Note that if you are building multiple machine
-versions of the shared library, the soft link is always set to the
-most recently built version.
-
-.. note::
-
-   If you are building LAMMPS with an MPI or FFT library or other
-   auxiliary libraries (used by various packages), then all of these
-   extra libraries must also be shared libraries.  If the LAMMPS
-   shared-library build fails with an error complaining about this, see
-   the :doc:`Build_basics <Build_basics>` doc page.
-
-Build LAMMPS as a shared library using CMake
---------------------------------------------
-
-When using CMake the following two options are necessary to generate the LAMMPS
-shared library:
-
-.. code-block:: bash
-
-   -D BUILD_SHARED_LIBS=on    # enable building of LAMMPS shared library (both options are needed!)
-
-What this does is create a liblammps.so which contains the majority of LAMMPS
-code. The generated lmp binary also dynamically links to this library. This
-means that either this liblammps.so file has to be in the same directory, a system
-library path (e.g. /usr/lib64/) or in the LD_LIBRARY_PATH.
-
-If you want to use the shared library with Python the recommended way is to create a virtualenv and use it as
-CMAKE_INSTALL_PREFIX.
-
-.. code-block:: bash
-
-   # create virtualenv
-   virtualenv --python=$(which python3) myenv3
-   source myenv3/bin/activate
-
-   # build library
-   mkdir build
-   cd build
-   cmake -D PKG_PYTHON=on -D BUILD_SHARED_LIBS=on -D CMAKE_INSTALL_PREFIX=$VIRTUAL_ENV ../cmake
-   make -j 4
-
-   # install into prefix
-   make install
-
-This will also install the Python module into your virtualenv. Since virtualenv
-does not change your LD_LIBRARY_PATH, you still need to add its lib64 folder to
-it, which contains the installed liblammps.so.
-
-.. code-block:: bash
-
-   export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib64:$LD_LIBRARY_PATH
-
-Starting Python outside (!) of your build directory, but with the virtualenv
-enabled and with the LD_LIBRARY_PATH set gives you access to LAMMPS via Python.

doc/src/Python_test.rst

@@ -1,152 +0,0 @@
-Test the Python/LAMMPS interface
-================================
-
-To test if LAMMPS is callable from Python, launch Python interactively
-and type:
-
-.. parsed-literal::
-
-   >>> from lammps import lammps
-   >>> lmp = lammps()
-
-If you get no errors, you're ready to use LAMMPS from Python.  If the
-second command fails, the most common error to see is
-
-.. parsed-literal::
-
-   OSError: Could not load LAMMPS dynamic library
-
-which means Python was unable to load the LAMMPS shared library.  This
-typically occurs if the system can't find the LAMMPS shared library or
-one of the auxiliary shared libraries it depends on, or if something
-about the library is incompatible with your Python.  The error message
-should give you an indication of what went wrong.
-
-You can also test the load directly in Python as follows, without
-first importing from the lammps.py file:
-
-.. parsed-literal::
-
-   >>> from ctypes import CDLL
-   >>> CDLL("liblammps.so")
-
-If an error occurs, carefully go through the steps on the
-:doc:`Build_basics <Build_basics>` doc page about building a shared
-library and the :doc:`Python_install <Python_install>` doc page about
-insuring Python can find the necessary two files it needs.
-
-Test LAMMPS and Python in serial:
--------------------------------------
-
-To run a LAMMPS test in serial, type these lines into Python
-interactively from the bench directory:
-
-.. parsed-literal::
-
-   >>> from lammps import lammps
-   >>> lmp = lammps()
-   >>> lmp.file("in.lj")
-
-Or put the same lines in the file test.py and run it as
-
-.. code-block:: bash
-
-   % python test.py
-
-Either way, you should see the results of running the in.lj benchmark
-on a single processor appear on the screen, the same as if you had
-typed something like:
-
-.. parsed-literal::
-
-   lmp_g++ -in in.lj
-
-Test LAMMPS and Python in parallel:
----------------------------------------
-
-To run LAMMPS in parallel, assuming you have installed the
-`PyPar <https://github.com/daleroberts/pypar>`_ package as discussed
-above, create a test.py file containing these lines:
-
-.. code-block:: python
-
-   import pypar
-   from lammps import lammps
-   lmp = lammps()
-   lmp.file("in.lj")
-   print "Proc %d out of %d procs has" % (pypar.rank(),pypar.size()),lmp
-   pypar.finalize()
-
-To run LAMMPS in parallel, assuming you have installed the
-`mpi4py <https://mpi4py.readthedocs.io>`_ package as discussed
-above, create a test.py file containing these lines:
-
-.. code-block:: python
-
-   from mpi4py import MPI
-   from lammps import lammps
-   lmp = lammps()
-   lmp.file("in.lj")
-   me = MPI.COMM_WORLD.Get_rank()
-   nprocs = MPI.COMM_WORLD.Get_size()
-   print "Proc %d out of %d procs has" % (me,nprocs),lmp
-   MPI.Finalize()
-
-You can either script in parallel as:
-
-.. code-block:: bash
-
-   % mpirun -np 4 python test.py
-
-and you should see the same output as if you had typed
-
-.. code-block:: bash
-
-   % mpirun -np 4 lmp_g++ -in in.lj
-
-Note that if you leave out the 3 lines from test.py that specify PyPar
-commands you will instantiate and run LAMMPS independently on each of
-the P processors specified in the mpirun command.  In this case you
-should get 4 sets of output, each showing that a LAMMPS run was made
-on a single processor, instead of one set of output showing that
-LAMMPS ran on 4 processors.  If the 1-processor outputs occur, it
-means that PyPar is not working correctly.
-
-Also note that once you import the PyPar module, PyPar initializes MPI
-for you, and you can use MPI calls directly in your Python script, as
-described in the PyPar documentation.  The last line of your Python
-script should be pypar.finalize(), to insure MPI is shut down
-correctly.
-
-Running Python scripts:
----------------------------
-
-Note that any Python script (not just for LAMMPS) can be invoked in
-one of several ways:
-
-.. code-block:: bash
-
-   % python foo.script
-   % python -i foo.script
-   % foo.script
-
-The last command requires that the first line of the script be
-something like this:
-
-.. code-block:: bash
-
-   #!/usr/local/bin/python
-   #!/usr/local/bin/python -i
-
-where the path points to where you have Python installed, and that you
-have made the script file executable:
-
-.. code-block:: bash
-
-   % chmod +x foo.script
-
-Without the "-i" flag, Python will exit when the script finishes.
-With the "-i" flag, you will be left in the Python interpreter when
-the script finishes, so you can type subsequent commands.  As
-mentioned above, you can only run Python interactively when running
-Python on a single processor, not in parallel.

doc/src/Python_trouble.rst

@@ -0,0 +1,44 @@
+Troubleshooting
+***************
+
+Testing if Python can launch LAMMPS
+===================================
+
+To test if LAMMPS is callable from Python, launch Python interactively
+and type:
+
+.. code-block:: python
+
+   >>> from lammps import lammps
+   >>> lmp = lammps()
+
+If you get no errors, you're ready to use LAMMPS from Python.  If the
+second command fails, the most common error to see is
+
+.. code-block:: bash
+
+   OSError: Could not load LAMMPS dynamic library
+
+which means Python was unable to load the LAMMPS shared library.  This
+typically occurs if the system can't find the LAMMPS shared library or
+one of the auxiliary shared libraries it depends on, or if something
+about the library is incompatible with your Python.  The error message
+should give you an indication of what went wrong.
+
+If your shared library uses a suffix, such as ``liblammps_mpi.so``, change
+the constructor call as follows (see :ref:`python_create_lammps` for more details):
+
+.. code-block:: python
+
+   >>> lmp = lammps(name='mpi')
+
+You can also test the load directly in Python as follows, without
+first importing from the lammps.py file:
+
+.. code-block:: python
+
+   >>> from ctypes import CDLL
+   >>> CDLL("liblammps.so")
+
+If an error occurs, carefully go through the steps in :ref:`python_install_guides` and on the
+:doc:`Build_basics <Build_basics>` doc page about building a shared library.

doc/src/Python_usage.rst

@@ -0,0 +1,569 @@
+.. _mpi4py_url: https://mpi4py.readthedocs.io/
+
+.. _python_create_lammps:
+
+Creating or deleting a LAMMPS object
+************************************
+
+With the Python interface the creation of a :cpp:class:`LAMMPS
+<LAMMPS_NS::LAMMPS>` instance is included in the constructors for the
+:py:class:`lammps <lammps.lammps>`, :py:class:`PyLammps <lammps.PyLammps>`,
+and :py:class:`IPyLammps <lammps.IPyLammps>` classes.
+Internally it will call either :cpp:func:`lammps_open` or :cpp:func:`lammps_open_no_mpi` from the C
+library API to create the class instance.
+
+All arguments are optional.  The *name* argument allows loading a
+LAMMPS shared library that is named ``liblammps_machine.so`` instead of
+the default name of ``liblammps.so``.  In most cases the latter will be
+installed or used.  The *ptr* argument is for use of the
+:py:mod:`lammps` module from inside a LAMMPS instance, e.g. with the
+:doc:`python <python>` command, where a pointer to the already existing
+:cpp:class:`LAMMPS <LAMMPS_NS::LAMMPS>` class instance can be passed
+to the Python class and used instead of creating a new instance.  The
+*comm* argument may be used in combination with the `mpi4py <mpi4py_url_>`_
+module to pass an MPI communicator to LAMMPS and thus it is possible
+to run the Python module like the library interface on a subset of the
+MPI ranks after splitting the communicator.
+
+
+Here are simple examples using all three Python interfaces:
+
+.. tabs::
+
+   .. tab:: lammps API
+
+      .. code-block:: python
+
+         from lammps import lammps
+
+         # NOTE: argv[0] is set by the lammps class constructor
+         args = ["-log", "none"]
+
+         # create LAMMPS instance
+         lmp = lammps(cmdargs=args)
+
+         # get and print numerical version code
+         print("LAMMPS Version: ", lmp.version())
+
+         # explicitly close and delete LAMMPS instance (optional)
+         lmp.close()
+
+   .. tab:: PyLammps API
+
+      The :py:class:`PyLammps <lammps.PyLammps>` class is a wrapper around the
+      :py:class:`lammps <lammps.lammps>` class and all of its lower level functions.
+      By default, it will create a new instance of :py:class:`lammps <lammps.lammps>` passing
+      along all arguments to the constructor of :py:class:`lammps <lammps.lammps>`.
+
+      .. code-block:: python
+
+         from lammps import PyLammps
+
+         # NOTE: argv[0] is set by the lammps class constructor
+         args = ["-log", "none"]
+
+         # create LAMMPS instance
+         L = PyLammps(cmdargs=args)
+
+         # get and print numerical version code
+         print("LAMMPS Version: ", L.version())
+
+         # explicitly close and delete LAMMPS instance (optional)
+         L.close()
+
+      :py:class:`PyLammps <lammps.PyLammps>` objects can also be created on top of an existing
+      :py:class:`lammps <lammps.lammps>` object:
+
+      .. code-block:: Python
+
+         from lammps import lammps, PyLammps
+         ...
+         # create LAMMPS instance
+         lmp = lammps(cmdargs=args)
+
+         # create PyLammps instance using previously created LAMMPS instance
+         L = PyLammps(ptr=lmp)
+
+      This is useful if you have to create the :py:class:`lammps <lammps.lammps>`
+      instance is a specific way, but want to take advantage of the
+      :py:class:`PyLammps <lammps.PyLammps>` interface.
+
+   .. tab:: IPyLammps API
+
+      The :py:class:`IPyLammps <lammps.IPyLammps>` class is an extension of the
+      :py:class:`PyLammps <lammps.PyLammps>` class. It has the same construction behavior. By
+      default, it will create a new instance of :py:class:`lammps` passing
+      along all arguments to the constructor of :py:class:`lammps`.
+
+      .. code-block:: python
+
+         from lammps import IPyLammps
+
+         # NOTE: argv[0] is set by the lammps class constructor
+         args = ["-log", "none"]
+
+         # create LAMMPS instance
+         L = IPyLammps(cmdargs=args)
+
+         # get and print numerical version code
+         print("LAMMPS Version: ", L.version())
+
+         # explicitly close and delete LAMMPS instance (optional)
+         L.close()
+
+      You can also initialize IPyLammps on top of an existing :py:class:`lammps` or :py:class:`PyLammps` object:
+
+      .. code-block:: Python
+
+         from lammps import lammps, IPyLammps
+         ...
+         # create LAMMPS instance
+         lmp = lammps(cmdargs=args)
+
+         # create PyLammps instance using previously created LAMMPS instance
+         L = PyLammps(ptr=lmp)
+
+      This is useful if you have to create the :py:class:`lammps <lammps.lammps>`
+      instance is a specific way, but want to take advantage of the
+      :py:class:`IPyLammps <lammps.IPyLammps>` interface.
+
+In all of the above cases, same as with the :ref:`C library API <lammps_c_api>`, this will use the
+``MPI_COMM_WORLD`` communicator for the MPI library that LAMMPS was
+compiled with.
+
+The :py:func:`lmp.close() <lammps.lammps.close()>` call is
+optional since the LAMMPS class instance will also be deleted
+automatically during the :py:class:`lammps <lammps.lammps>` class
+destructor.
+
+Note that you can create multiple LAMMPS objects in your Python
+script, and coordinate and run multiple simulations, e.g.
+
+.. code-block:: Python
+
+   from lammps import lammps
+   lmp1 = lammps()
+   lmp2 = lammps()
+   lmp1.file("in.file1")
+   lmp2.file("in.file2")
+
+Executing LAMMPS commands
+*************************
+
+Once an instance of the :py:class:`lammps <lammps.lammps>`,
+:py:class:`PyLammps <lammps.PyLammps>`, or
+:py:class:`IPyLammps <lammps.IPyLammps>` class is created, there are
+multiple ways to "feed" it commands. In a way that is not very different from
+running a LAMMPS input script, except that Python has many more facilities
+for structured programming than the LAMMPS input script syntax. Furthermore
+it is possible to "compute" what the next LAMMPS command should be.
+
+.. tabs::
+
+   .. tab:: lammps API
+
+      Same as in the equivalent
+      :doc:`C library functions <Library_execute>`, commands can be read from a file, a
+      single string, a list of strings and a block of commands in a single
+      multi-line string. They are processed under the same boundary conditions
+      as the C library counterparts.  The example below demonstrates the use
+      of :py:func:`lammps.file()`, :py:func:`lammps.command()`,
+      :py:func:`lammps.commands_list()`, and :py:func:`lammps.commands_string()`:
+
+      .. code-block:: python
+
+         from lammps import lammps
+         lmp = lammps()
+
+         # read commands from file 'in.melt'
+         lmp.file('in.melt')
+
+         # issue a single command
+         lmp.command('variable zpos index 1.0')
+
+         # create 10 groups with 10 atoms each
+         cmds = ["group g{} id {}:{}".format(i,10*i+1,10*(i+1)) for i in range(10)]
+         lmp.commands_list(cmds)
+
+         # run commands from a multi-line string
+         block = """
+         clear
+         region  box block 0 2 0 2 0 2
+         create_box 1 box
+         create_atoms 1 single 1.0 1.0 ${zpos}
+         """
+         lmp.commands_string(block)
+
+   .. tab:: PyLammps/IPyLammps API
+
+      Unlike the lammps API, the PyLammps/IPyLammps APIs allow running LAMMPS
+      commands by calling equivalent member functions of :py:class:`PyLammps <lammps.PyLammps>`
+      and :py:class:`IPyLammps <lammps.IPyLammps>` instances.
+
+      For instance, the following LAMMPS command
+
+      .. code-block:: LAMMPS
+
+         region box block 0 10 0 5 -0.5 0.5
+
+      can be executed using with the lammps AI with the following Python code if *L* is an
+      instance of :py:class:`lammps <lammps.lammps>`:
+
+      .. code-block:: Python
+
+         L.command("region box block 0 10 0 5 -0.5 0.5")
+
+      With the PyLammps interface, any LAMMPS command can be split up into arbitrary parts.
+      These parts are then passed to a member function with the name of the command.
+      For the ``region`` command that means the :code:`region()` method can be called.
+      The arguments of the command can be passed as one string, or
+      individually.
+
+      .. code-block:: Python
+
+         L.region("box block", 0, 10, 0, 5, -0.5, 0.5)
+
+      In this example all parameters except the first are Python floating-point literals. The
+      PyLammps interface takes the entire parameter list and transparently
+      merges it to a single command string.
+
+      The benefit of this approach is avoiding redundant command calls and easier
+      parameterization. In the original interface parameterization this needed to be done
+      manually by creating formatted strings.
+
+      .. code-block:: Python
+
+         L.command("region box block %f %f %f %f %f %f" % (xlo, xhi, ylo, yhi, zlo, zhi))
+
+      In contrast, methods of PyLammps accept parameters directly and will convert
+      them automatically to a final command string.
+
+      .. code-block:: Python
+
+         L.region("box block", xlo, xhi, ylo, yhi, zlo, zhi)
+
+      Using these facilities, the example shown for the lammps API can be rewritten as follows:
+
+      .. code-block:: python
+
+         from lammps import PyLammps
+         L = PyLammps()
+
+         # read commands from file 'in.melt'
+         L.file('in.melt')
+
+         # issue a single command
+         L.variable('zpos', 'index', 1.0)
+
+         # create 10 groups with 10 atoms each
+         for i in range(10):
+            L.group(f"g{i}", "id", f"{10*i+1}:{10*(i+1)}")
+
+         L.clear()
+         L.region("box block", 0, 2, 0, 2, 0, 2)
+         L.create_box(1, "box")
+         L.create_atoms(1, "single", 1.0, 1.0, "${zpos}")
+
+
+Retrieving or setting LAMMPS system properties
+**********************************************
+
+Similar to what is described in :doc:`Library_properties`, the instances of
+:py:class:`lammps <lammps.lammps>`, :py:class:`PyLammps <lammps.PyLammps>`, or
+:py:class:`IPyLammps <lammps.IPyLammps>` can be used to extract different kinds
+of information about the active LAMMPS instance and also to modify some of it. The
+main difference between the interfaces is how the information is exposed.
+
+While the :py:class:`lammps <lammps.lammps>` is just a thin layer that wraps C API calls,
+:py:class:`PyLammps <lammps.PyLammps>` and :py:class:`IPyLammps <lammps.IPyLammps>` expose
+information as objects and properties.
+
+In some cases the data returned is a direct reference to the original data
+inside LAMMPS cast to ``ctypes`` pointers. Where possible, the wrappers will
+determine the ``ctypes`` data type and cast pointers accordingly. If
+``numpy`` is installed arrays can also be extracted as numpy arrays, which
+will access the C arrays directly and have the correct dimensions to protect
+against invalid accesses.
+
+.. warning::
+
+   When accessing per-atom data,
+   please note that this data is the per-processor local data and indexed
+   accordingly. These arrays can change sizes and order at every neighbor list
+   rebuild and atom sort event as atoms are migrating between sub-domains.
+
+.. tabs::
+
+   .. tab:: lammps API
+
+      .. code-block:: python
+
+         from lammps import lammps
+
+         lmp = lammps()
+         lmp.file("in.sysinit")
+
+         natoms = lmp.get_natoms()
+         print(f"running simulation with {natoms} atoms")
+
+         lmp.command("run 1000 post no");
+
+         for i in range(10):
+            lmp.command("run 100 pre no post no")
+            pe = lmp.get_thermo("pe")
+            ke = lmp.get_thermo("ke")
+            print(f"PE = {pe}\nKE = {ke}")
+
+         lmp.close()
+
+      **Methods**:
+
+      * :py:meth:`version() <lammps.lammps.version()>`: return the numerical version id, e.g. LAMMPS 2 Sep 2015 -> 20150902
+      * :py:meth:`get_thermo() <lammps.lammps.get_thermo()>`: return current value of a thermo keyword
+      * :py:meth:`get_natoms() <lammps.lammps.get_natoms()>`: total # of atoms as int
+      * :py:meth:`reset_box() <lammps.lammps.reset_box()>`: reset the simulation box size
+      * :py:meth:`extract_setting() <lammps.lammps.extract_setting()>`: return a global setting
+      * :py:meth:`extract_global() <lammps.lammps.extract_global()>`: extract a global quantity
+      * :py:meth:`extract_atom() <lammps.lammps.extract_atom()>`: extract a per-atom quantity
+      * :py:meth:`extract_box() <lammps.lammps.extract_box()>`: extract box info
+      * :py:meth:`create_atoms() <lammps.lammps.create_atoms()>`: create N atoms with IDs, types, x, v, and image flags
+
+      **Numpy Methods**:
+
+      * :py:meth:`numpy.extract_atom() <lammps.numpy_wrapper.extract_atom()>`: extract a per-atom quantity as numpy array
+
+   .. tab:: PyLammps/IPyLammps API
+
+      In addition to the functions provided by :py:class:`lammps <lammps.lammps>`, :py:class:`PyLammps <lammps.PyLammps>` objects
+      have several properties which allow you to query the system state:
+
+      L.system
+         Is a dictionary describing the system such as the bounding box or number of atoms
+
+      L.system.xlo, L.system.xhi
+         bounding box limits along x-axis
+
+      L.system.ylo, L.system.yhi
+         bounding box limits along y-axis
+
+      L.system.zlo, L.system.zhi
+         bounding box limits along z-axis
+
+      L.communication
+         configuration of communication subsystem, such as the number of threads or processors
+
+      L.communication.nthreads
+         number of threads used by each LAMMPS process
+
+      L.communication.nprocs
+         number of MPI processes used by LAMMPS
+
+      L.fixes
+         List of fixes in the current system
+
+      L.computes
+         List of active computes in the current system
+
+      L.dump
+         List of active dumps in the current system
+
+      L.groups
+         List of groups present in the current system
+
+      **Retrieving the value of an arbitrary LAMMPS expressions**
+
+      LAMMPS expressions can be immediately evaluated by using the ``eval`` method. The
+      passed string parameter can be any expression containing global :doc:`thermo` values,
+      variables, compute or fix data (see :doc:`Howto_output`):
+
+
+      .. code-block:: Python
+
+         result = L.eval("ke") # kinetic energy
+         result = L.eval("pe") # potential energy
+
+         result = L.eval("v_t/2.0")
+
+      **Example**
+
+      .. code-block:: python
+
+         from lammps import PyLammps
+
+         L = PyLammps()
+         L.file("in.sysinit")
+
+         print(f"running simulation with {L.system.natoms} atoms")
+
+         L.run(1000, "post no");
+
+         for i in range(10):
+            L.run(100, "pre no post no")
+            pe = L.eval("pe")
+            ke = L.eval("ke")
+            print(f"PE = {pe}\nKE = {ke}")
+
+
+
+Retrieving or setting properties of LAMMPS objects
+**************************************************
+
+This section documents accessing or modifying data from objects like
+computes, fixes, or variables in LAMMPS using the :py:mod:`lammps` module.
+
+.. tabs::
+
+   .. tab:: lammps API
+
+      For :py:meth:`lammps.extract_compute() <lammps.lammps.extract_compute()>` and
+      :py:meth:`lammps.extract_fix() <lammps.lammps.extract_fix()>`, the global, per-atom,
+      or local data calculated by the compute or fix can be accessed. What is returned
+      depends on whether the compute or fix calculates a scalar or vector or array.
+      For a scalar, a single double value is returned.  If the compute or fix calculates
+      a vector or array, a pointer to the internal LAMMPS data is returned, which you can
+      use via normal Python subscripting.
+
+      The one exception is that for a fix that calculates a
+      global vector or array, a single double value from the vector or array
+      is returned, indexed by I (vector) or I and J (array).  I,J are
+      zero-based indices.
+      See the :doc:`Howto output <Howto_output>` doc page for a discussion of
+      global, per-atom, and local data, and of scalar, vector, and array
+      data types.  See the doc pages for individual :doc:`computes <compute>`
+      and :doc:`fixes <fix>` for a description of what they calculate and
+      store.
+
+      For :py:meth:`lammps.extract_variable() <lammps.lammps.extract_variable()>`,
+      an :doc:`equal-style or atom-style variable <variable>` is evaluated and
+      its result returned.
+
+      For equal-style variables a single ``c_double`` value is returned and the
+      group argument is ignored.  For atom-style variables, a vector of
+      ``c_double`` is returned, one value per atom, which you can use via normal
+      Python subscripting. The values will be zero for atoms not in the
+      specified group.
+
+      :py:meth:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.extract_compute()>`,
+      :py:meth:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.extract_fix()>`, and
+      :py:meth:`lammps.numpy.extract_variable() <lammps.numpy_wrapper.extract_variable()>` are
+      equivalent NumPy implementations that return NumPy arrays instead of ``ctypes`` pointers.
+
+      The :py:meth:`lammps.set_variable() <lammps.lammps.set_variable()>` method sets an
+      existing string-style variable to a new string value, so that subsequent LAMMPS
+      commands can access the variable.
+
+      **Methods**:
+
+      * :py:meth:`lammps.extract_compute() <lammps.lammps.extract_compute()>`: extract value(s) from a compute
+      * :py:meth:`lammps.extract_fix() <lammps.lammps.extract_fix()>`: extract value(s) from a fix
+      * :py:meth:`lammps.extract_variable() <lammps.lammps.extract_variable()>`: extract value(s) from a variable
+      * :py:meth:`lammps.set_variable() <lammps.lammps.set_variable()>`: set existing named string-style variable to value
+
+      **NumPy Methods**:
+
+      * :py:meth:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.extract_compute()>`: extract value(s) from a compute, return arrays as numpy arrays
+      * :py:meth:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.extract_fix()>`: extract value(s) from a fix, return arrays as numpy arrays
+      * :py:meth:`lammps.numpy.extract_variable() <lammps.numpy_wrapper.extract_variable()>`: extract value(s) from a variable, return arrays as numpy arrays
+
+
+   .. tab:: PyLammps/IPyLammps API
+
+      PyLammps and IPyLammps classes currently do not add any additional ways of
+      retrieving information out of computes and fixes. This information can still be accessed by using the lammps API:
+
+      .. code-block:: python
+
+         L.lmp.extract_compute(...)
+         L.lmp.extract_fix(...)
+         # OR
+         L.lmp.numpy.extract_compute(...)
+         L.lmp.numpy.extract_fix(...)
+
+      LAMMPS variables can be both defined and accessed via the :py:class:`PyLammps <lammps.PyLammps>` interface.
+
+      To define a variable you can use the :doc:`variable <variable>` command:
+
+      .. code-block:: Python
+
+         L.variable("a index 2")
+
+      A dictionary of all variables is returned by the :py:attr:`PyLammps.variables <lammps.PyLammps.variables>` property:
+
+      you can access an individual variable by retrieving a variable object from the
+      ``L.variables`` dictionary by name
+
+      .. code-block:: Python
+
+         a = L.variables['a']
+
+      The variable value can then be easily read and written by accessing the value
+      property of this object.
+
+      .. code-block:: Python
+
+         print(a.value)
+         a.value = 4
+
+
+
+Gather and Scatter Data between MPI processors
+**********************************************
+
+.. code-block:: Python
+
+   data = lmp.gather_atoms(name,type,count)  # return per-atom property of all atoms gathered into data, ordered by atom ID
+                                             # name = "x", "charge", "type", etc
+   data = lmp.gather_atoms_concat(name,type,count)  # ditto, but concatenated atom values from each proc (unordered)
+   data = lmp.gather_atoms_subset(name,type,count,ndata,ids)  # ditto, but for subset of Ndata atoms with IDs
+
+   lmp.scatter_atoms(name,type,count,data)   # scatter per-atom property to all atoms from data, ordered by atom ID
+                                             # name = "x", "charge", "type", etc
+                                             # count = # of per-atom values, 1 or 3, etc
+
+   lmp.scatter_atoms_subset(name,type,count,ndata,ids,data)  # ditto, but for subset of Ndata atoms with IDs
+
+
+The gather methods 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.
+
+Note that the data returned by the gather methods,
+e.g. gather_atoms("x"), is different from the data structure returned
+by extract_atom("x") in four ways.  (1) Gather_atoms() returns a
+vector which you index as x[i]; extract_atom() returns an array
+which you index as x[i][j].  (2) Gather_atoms() orders the atoms
+by atom ID while extract_atom() does not.  (3) Gather_atoms() returns
+a list of all atoms in the simulation; extract_atoms() returns just
+the atoms local to each processor.  (4) Finally, the gather_atoms()
+data structure is a copy of the atom coords stored internally in
+LAMMPS, whereas extract_atom() returns an array that effectively
+points directly to the internal data.  This means you can change
+values inside LAMMPS from Python by assigning a new values to the
+extract_atom() array.  To do this with the gather_atoms() vector, you
+need to change values in the vector, then invoke the scatter_atoms()
+method.
+
+For the scatter methods, the array of coordinates passed to must be a
+ctypes vector of ints or doubles, allocated and initialized something
+like this:
+
+.. code-block:: Python
+
+   from ctypes import c_double
+   natoms = lmp.get_natoms()
+   n3 = 3*natoms
+   x = (n3*c_double)()
+   x[0] = x coord of atom with ID 1
+   x[1] = y coord of atom with ID 1
+   x[2] = z coord of atom with ID 1
+   x[3] = x coord of atom with ID 2
+   ...
+   x[n3-1] = z coord of atom with ID natoms
+   lmp.scatter_atoms("x",1,3,x)
+
+Alternatively, you can just change values in the vector returned by
+the gather methods, since they are also ctypes vectors.
+

doc/src/Speed_kokkos.rst

@@ -27,6 +27,7 @@ GPUs) and HIP (for AMD GPUs). You choose the mode at build time to
 produce an executable compatible with a specific hardware.
 
 .. admonition:: NVIDIA CUDA support
+   :class: note
 
    To build with Kokkos support for NVIDIA GPUs, the NVIDIA CUDA toolkit
    software version 9.0 or later must be installed on your system. See
@@ -34,6 +35,7 @@ produce an executable compatible with a specific hardware.
    how to check and do this.
 
 .. admonition:: CUDA and MPI library compatibility
+   :class: note
 
    Kokkos with CUDA currently implicitly assumes that the MPI library is
    CUDA-aware. This is not always the case, especially when using
@@ -46,6 +48,7 @@ produce an executable compatible with a specific hardware.
    cuda/aware off <package>` in the input file.
 
 .. admonition:: AMD GPU support
+   :class: note
 
    To build with Kokkos the HIPCC compiler from the AMD ROCm software
    version 3.5 or later is required.  Supporting this Kokkos mode in

doc/src/Tools.rst

@@ -92,6 +92,7 @@ Miscellaneous tools
    * :ref:`emacs <emacs>`
    * :ref:`i-pi <ipi>`
    * :ref:`kate <kate>`
+   * :ref:`LAMMPS shell <lammps_shell>`
    * :ref:`singularity <singularity_tool>`
    * :ref:`vim <vim>`
 
@@ -397,10 +398,141 @@ The file was provided by Alessandro Luigi Sellerio
 
 ----------
 
+.. _lammps_shell:
+
+LAMMPS shell
+------------
+
+.. versionadded:: 9Oct2020
+
+Overview
+========
+
+The LAMMPS Shell, ``lammps-shell`` is a program that functions very
+similar to the regular LAMMPS executable but has several modifications
+and additions that make it more powerful for interactive sessions,
+i.e. where you type LAMMPS commands from the prompt instead of reading
+them from a file.
+
+- It uses the readline and history libraries to provide command line
+  editing and context aware TAB-expansion (details on that below).
+
+- When processing an input file with the '-in' or '-i' flag from the
+  command line, it does not exit at the end of that input file but
+  stops at a prompt, so that additional commands can be issued
+
+- Errors will not abort the shell but return to the prompt.
+
+- It has additional commands aimed at interactive use (details below).
+
+- Interrupting a calculation with CTRL-C will not terminate the
+  session but rather enforce a timeout to cleanly stop an ongoing
+  run (more info on timeouts is in the timer command documentation).
+
+These enhancements makes the LAMMPS shell an attractive choice for
+interactive LAMMPS sessions in graphical user interfaces.
+
+TAB-expansion
+=============
+
+When writing commands interactively at the shell prompt, you can hit
+the TAB key at any time to try and complete the text.  This completion
+is context aware and will expand any first word only to commands
+available in that executable.
+
+- For style commands it will expand to available styles of the
+  corresponding category (e.g. pair styles after a
+  :doc:`pair_style <pair_style>` command).
+
+- For :doc:`compute <compute>`, :doc:`fix <fix>`, or :doc:`dump <dump>`
+  it will also expand only to already defined groups for the group-ID
+  keyword.
+
+- For commands like :doc:`compute_modify <compute_modify>`,
+  :doc:`fix_modify <fix_modify>`, or :doc:`dump_modify <dump_modify>`
+  it will expand to known compute/fix/dump IDs only.
+
+- When typing references to computes, fixes, or variables with a
+  "c\_", "f\_", or "v\_" prefix, respectively, then the expansion will
+  be to known compute/fix IDs and variable names. Variable name
+  expansion is also available for the ${name} variable syntax.
+
+- In all other cases TAB expansion will complete to names of files
+  and directories.
+
+Command line editing and history
+================================
+
+When typing commands, command line editing similar to what BASH
+provides is available.  Thus it is possible to move around the
+currently line and perform various cut and insert and edit operations.
+Previous commands can be retrieved by scrolling up (and down)
+or searching (e.g. with CTRL-r).
+
+Also history expansion through using the exclamation mark '!'
+can be performed.  Examples: '!!' will be replaced with the previous
+command, '!-2' will repeat the command before that, '!30' will be
+replaced with event number 30 in the command history list, and
+'!run' with the last command line that started with "run".  Adding
+a ":p" to such a history expansion will result that the expansion is
+printed and added to the history list, but NOT executed.
+On exit the LAMMPS shell will write the history list to a file
+".lammps_history" in the current working directory.  If such a
+file exists when the LAMMPS shell is launched it will be read to
+populate the history list.
+
+This is realized via the readline library and can thus be customized
+with an ``.inputrc`` file in the home directory.  For application
+specific customization, the LAMMPS shell uses the name "lammps-shell".
+For more information about using and customizing an application using
+readline, please see the available documentation at:
+`http://www.gnu.org/s/readline/#Documentation
+<http://www.gnu.org/s/readline/#Documentation>`_
+
+Additional commands
+===================
+
+The following commands are added to the LAMMPS shell on top of the
+regular LAMMPS commands:
+
+.. parsed-literal::
+
+   help (or ?)    print a brief help message
+   history        display the current command history list
+   clear_history  wipe out the current command history list
+   pwd            print current working directory
+   cd <directory> change current working directory (same as pwd if no directory)
+   mem            print current and maximum memory usage
+   \|<command>     execute <command> as a shell command and return to the command prompt
+   exit           exit the LAMMPS shell cleanly (unlike the "quit" command)
+
+Please note that some known shell operations are implemented in the
+LAMMPS :doc:`shell command <shell>` in a platform neutral fashion,
+while using the '\|' character will always pass the following text
+to the operating system's shell command.
+
+Compilation
+===========
+
+Compilation of the LAMMPS shell can be enabled by setting the CMake
+variable ``BUILD_LAMMPS_SHELL`` to "on" or using the makefile in the
+``tools/lammps-shell`` folder to compile after building LAMMPS using
+the conventional make procedure.  The makefile will likely need
+customization depending on the features and settings used for
+compiling LAMMPS.
+
+Limitations
+===========
+
+The LAMMPS shell was not designed for use with MPI parallelization
+via ``mpirun`` or ``mpiexec`` or ``srun``.
+
+----------
+
 .. _arc:
 
 lmp2arc tool
-----------------------
+------------
 
 The lmp2arc sub-directory contains a tool for converting LAMMPS output
 files to the format for Accelrys' Insight MD code (formerly
@@ -663,6 +795,7 @@ The singularity sub-directory contains container definitions files
 that can be used to build container images for building and testing
 LAMMPS on specific OS variants using the `Singularity <https://sylabs.io>`_
 container software. Contributions for additional variants are welcome.
+For more details please see the README.md file in that folder.
 
 ----------
 

doc/src/compute_centro_atom.rst

@@ -133,7 +133,7 @@ simulation into gold (FCC).  These were provided by Jon Zimmerman
    Stacking faults ~ 5.0 (4.0 to 6.0)
    Free surface ~ 23.0
 
-These values are \*not\* normalized by the square of the lattice
+These values are **not** normalized by the square of the lattice
 parameter.  If they were, normalized values would be:
 
 .. parsed-literal::

doc/src/compute_tally.rst

@@ -107,8 +107,8 @@ The computes in this package are not compatible with dynamic groups.
 Related commands
 """"""""""""""""
 
-*compute group/group*\ _compute_group_group.html, *compute
+* :doc:`compute group/group <compute_group_group>`
-heat/flux*\ _compute_heat_flux.html
+* :doc:`compute heat/flux <compute_heat_flux>`
 
 Default
 """""""

doc/src/dump_cfg_uef.rst

@@ -24,8 +24,8 @@ Examples
 
 .. code-block:: LAMMPS
 
-   dump 1 all cfg/uef 10 dump.\*.cfg mass type xs ys zs
+   dump 1 all cfg/uef 10 dump.*.cfg mass type xs ys zs
-   dump 2 all cfg/uef 100 dump.\*.cfg mass type xs ys zs id c_stress
+   dump 2 all cfg/uef 100 dump.*.cfg mass type xs ys zs id c_stress
 
 Description
 """""""""""

doc/src/dump_image.rst

@@ -21,7 +21,7 @@ Syntax
 * color = atom attribute that determines color of each atom
 * diameter = atom attribute that determines size of each atom
 * zero or more keyword/value pairs may be appended
-* keyword = *atom* or *adiam* or *bond* or *line* or *tri* or *body* or *fix* or *size* or *view* or *center* or *up* or *zoom* or *persp* or *box* or *axes* or *subbox* or *shiny* or *ssao*
+* keyword = *atom* or *adiam* or *bond* or *line* or *tri* or *body* or *fix* or *size* or *view* or *center* or *up* or *zoom* or *box* or *axes* or *subbox* or *shiny* or *ssao*
 
   .. parsed-literal::
 
@@ -62,9 +62,6 @@ Syntax
        *zoom* value = zfactor = size that simulation box appears in image
          zfactor = scale image size by factor > 1 to enlarge, factor < 1 to shrink
          zfactor can be a variable (see below)
-       *persp* value = pfactor = amount of "perspective" in image
-         pfactor = amount of perspective (0 = none, < 1 = some, > 1 = highly skewed)
-         pfactor can be a variable (see below)
        *box* values = yes/no diam = draw outline of simulation box
          yes/no = do or do not draw simulation box lines
          diam = diameter of box lines as fraction of shortest box length
@@ -87,9 +84,9 @@ Examples
 
 .. code-block:: LAMMPS
 
-   dump d0 all image 100 dump.\*.jpg type type
+   dump d0 all image 100 dump.*.jpg type type
-   dump d1 mobile image 500 snap.\*.png element element ssao yes 4539 0.6
+   dump d1 mobile image 500 snap.*.png element element ssao yes 4539 0.6
-   dump d2 all image 200 img-\*.ppm type type zoom 2.5 adiam 1.5 size 1280 720
+   dump d2 all image 200 img-*.ppm type type zoom 2.5 adiam 1.5 size 1280 720
    dump m0 all movie 1000 movie.mpg type type size 640 480
    dump m1 all movie 1000 movie.avi type type size 640 480
    dump m2 all movie 100 movie.m4v type type zoom 1.8 adiam v_value size 1280 720
@@ -426,13 +423,14 @@ i.e. the number of pixels in each direction.
 
 ----------
 
-The *view*\ , *center*\ , *up*\ , *zoom*\ , and *persp* values determine how
+The *view*\ , *center*\ , *up*\ , and *zoom* values determine how
 3d simulation space is mapped to the 2d plane of the image.  Basically
 they control how the simulation box appears in the image.
 
-All of the *view*\ , *center*\ , *up*\ , *zoom*\ , and *persp* values can be
+All of the *view*\ , *center*\ , *up*\ , and *zoom* values can be
 specified as numeric quantities, whose meaning is explained below.
-Any of them can also be specified as an :doc:`equal-style variable <variable>`, by using v_name as the value, where "name" is
+Any of them can also be specified as an :doc:`equal-style variable <variable>`,
+by using v_name as the value, where "name" is
 the variable name.  In this case the variable will be evaluated on the
 timestep each image is created to create a new value.  If the
 equal-style variable is time-dependent, this is a means of changing
@@ -483,19 +481,6 @@ image mostly filled by the atoms in the simulation box.  A *zfactor* >
 1 will make the simulation box larger; a *zfactor* < 1 will make it
 smaller.  *Zfactor* must be a value > 0.0.
 
-The *persp* keyword determines how much depth perspective is present
-in the image.  Depth perspective makes lines that are parallel in
-simulation space appear non-parallel in the image.  A *pfactor* value
-of 0.0 means that parallel lines will meet at infinity (1.0/pfactor),
-which is an orthographic rendering with no perspective.  A *pfactor*
-value between 0.0 and 1.0 will introduce more perspective.  A *pfactor*
-value > 1 will create a highly skewed image with a large amount of
-perspective.
-
-.. note::
-
-   The *persp* keyword is not yet supported as an option.
-
 ----------
 
 The *box* keyword determines if and how the simulation box boundaries
@@ -692,7 +677,6 @@ The defaults for the keywords are as follows:
 * up = 0 0 1 (for 3d)
 * up = 0 1 0 (for 2d)
 * zoom = 1.0
-* persp = 0.0
 * box = yes 0.02
 * axes = no 0.0 0.0
 * subbox no 0.0

doc/src/fix_property_atom.rst

@@ -106,6 +106,7 @@ when ghost atoms are created (at every re-neighboring) to insure the
 new properties are also defined for the ghost atoms.
 
 .. admonition:: Properties on ghost atoms
+   :class: note
 
    If you use this command with the *mol*\ , *q* or *rmass* vectors,
    then you most likely want to set *ghost* yes, since these properties
@@ -116,6 +117,7 @@ new properties are also defined for the ghost atoms.
    those vectors but do not set *ghost* yes.
 
 .. admonition:: Limitations on ghost atom properties
+   :class: note
 
    The properties for ghost atoms are not updated every timestep,
    but only once every few steps when neighbor lists are re-built.  Thus

doc/src/fix_wall_gran.rst

@@ -205,11 +205,11 @@ the following table:
 +-------+----------------------------------------------------+----------------+
 |     4 | Force :math:`f_z` exerted on the wall              | force units    |
 +-------+----------------------------------------------------+----------------+
-|     5 | :math:`\Delta x` between wall surface and particle | distance units |
+|     5 | :math:`x`-coordinate of contact point on wall      | distance units |
 +-------+----------------------------------------------------+----------------+
-|     6 | :math:`\Delta y` between wall surface and particle | distance units |
+|     6 | :math:`y`-coordinate of contact point on wall      | distance units |
 +-------+----------------------------------------------------+----------------+
-|     7 | :math:`\Delta z` between wall surface and particle | distance units |
+|     7 | :math:`z`-coordinate of contact point on wall      | distance units |
 +-------+----------------------------------------------------+----------------+
 |     8 | Radius :math:`r` of atom                           | distance units |
 +-------+----------------------------------------------------+----------------+

doc/src/fix_wall_gran_region.rst

@@ -246,11 +246,11 @@ the following table:
 +-------+----------------------------------------------------+----------------+
 |     4 | Force :math:`f_z` exerted on the wall              | force units    |
 +-------+----------------------------------------------------+----------------+
-|     5 | :math:`\Delta x` between wall surface and particle | distance units |
+|     5 | :math:`x`-coordinate of contact point on wall      | distance units |
 +-------+----------------------------------------------------+----------------+
-|     6 | :math:`\Delta y` between wall surface and particle | distance units |
+|     6 | :math:`y`-coordinate of contact point on wall      | distance units |
 +-------+----------------------------------------------------+----------------+
-|     7 | :math:`\Delta z` between wall surface and particle | distance units |
+|     7 | :math:`z`-coordinate of contact point on wall      | distance units |
 +-------+----------------------------------------------------+----------------+
 |     8 | Radius :math:`r` of atom                           | distance units |
 +-------+----------------------------------------------------+----------------+

doc/src/if.rst

@@ -140,12 +140,12 @@ clarity, you must enclose the entire expression in quotes.
 
 An expression is built out of numbers (which start with a digit or
 period or minus sign) or strings (which start with a letter and can
-contain alphanumeric characters or underscores):
+contain alphanumeric characters, underscores, or forward slashes):
 
 .. parsed-literal::
 
-   0.2, 100, 1.0e20, -15.4, etc
+   0.2, 100, 1.0e20, -15.4, ...
-   InP, myString, a123, ab_23_cd, etc
+   InP, myString, a123, ab_23_cd, lj/cut, ...
 
 and Boolean operators:
 

doc/src/pair_coul_tt.rst

@@ -0,0 +1,131 @@
+.. index:: pair_style coul/tt
+
+pair_style coul/tt command
+==========================
+
+Syntax
+""""""
+
+.. code-block:: LAMMPS
+
+   pair_style style args
+
+* style = *coul/tt*
+* args = list of arguments for a particular style
+
+.. parsed-literal::
+
+     *coul/tt* args = n cutoff
+       n = degree of polynomial
+       cutoff = global cutoff (distance units)
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+   pair_style hybrid/overlay ... coul/tt 4 12.0
+   pair_coeff 1 2  coul/tt 4.5 1.0
+   pair_coeff 1 2  coul/tt 4.0 1.0 4 12.0
+   pair_coeff 1 3* coul/tt 4.5 1.0 4
+
+
+Description
+"""""""""""
+
+The *coul/tt* pair style is meant to be used with force fields that
+include explicit polarization through Drude dipoles.
+
+The *coul/tt* pair style should be used as a sub-style within in the
+:doc:`pair_style hybrid/overlay <pair_hybrid>` command, in conjunction with a
+main pair style including Coulomb interactions and *thole* pair style,
+or with *lj/cut/thole/long* pair style that is equivalent to the combination
+of preceding two.
+
+The *coul/tt* pair styles compute the charge-dipole Coulomb interaction damped
+at short distances by a function
+
+.. math::
+
+  f_{n,ij}(r) = 1 - c_{ij} \cdot e^{-b_{ij} r} \sum_{k=0}^n \frac{(b_{ij} r)^k}{k!}
+
+This function results from an adaptation to the Coulomb interaction :ref:`(Salanne)
+<Salanne1>` of the damping function originally proposed
+by :ref:`Tang Toennies <TangToennies1>` for van der Waals interactions.
+
+The polynomial takes the degree 4 for damping the Coulomb interaction.
+The parameters :math:`b_{ij}` and :math:`c_{ij}` could be determined from
+first-principle calculations for small, mainly mono-atomic, ions :ref:`(Salanne)
+<Salanne1>`, or else treated as empirical for large molecules.
+
+In pair styles with Drude induced dipoles, this damping function is typically
+applied to the interactions between a Drude charge (either :math:`q_{D,i}` on
+a Drude particle or :math:`-q_{D,i}` on the respective
+Drude core)) and a charge on a non-polarizable atom, :math:`q_{j}`.
+
+The Tang-Toennies function could also be used to damp electrostatic
+interactions between the (non-polarizable part of the) charge of a core,
+:math:`q_{i}-q_{D,i}`, and the Drude charge of another, :math:`-q_{D,j}`.
+The :math:`b_{ij}` and :math:`c_{ij}` are equal  to :math:`b_{ji}` and
+:math:`c_{ji}` in the case of core-core interactions.
+
+For pair_style *coul/tt*\ , the following coefficients must be defined for
+each pair of atoms types via the :doc:`pair_coeff <pair_coeff>` command
+as in the example above.
+
+* :math:`b_{ij}`
+* :math:`c_{ij}`
+* degree of polynomial (positive integer)
+* cutoff (distance units)
+
+The last two coefficients are optional.  If not specified the global
+degree of the polynomial or the global cutoff specified in the pair_style
+command are used. In order to specify a cutoff (forth argument), the degree of
+the polynomial (third argument) must also be specified.
+
+----------
+
+Mixing, shift, table, tail correction, restart, rRESPA info
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+The *coul/tt* pair style does not support mixing.  Thus, coefficients
+for all I,J pairs must be specified explicitly.
+
+Restrictions
+""""""""""""
+
+These pair styles are part of the USER-DRUDE package. They are only
+enabled if LAMMPS was built with that package. See the :doc:`Build package
+<Build_package>` doc page for more info.
+
+This pair_style should currently not be used with the :doc:`charmm dihedral
+style <dihedral_charmm>` if the latter has non-zero 1-4 weighting
+factors. This is because the *coul/tt* pair style does not know which
+pairs are 1-4 partners of which dihedrals.
+
+Related commands
+""""""""""""""""
+
+:doc:`fix drude <fix_drude>`, :doc:`fix langevin/drude <fix_langevin_drude>`,
+:doc:`fix drude/transform <fix_drude_transform>`,
+:doc:`compute temp/drude <compute_temp_drude>`,
+:doc:`pair_style thole <pair_thole>`
+
+Default
+"""""""
+
+none
+
+----------
+
+.. _Thole3:
+
+**(Thole)** Chem Phys, 59, 341 (1981).
+
+.. _Salanne1:
+
+**(Salanne)** Salanne, Rotenberg, Jahn, Vuilleumier, Simon, Christian and Madden, Theor Chem Acc, 131, 1143 (2012).
+
+.. _TangToennies1:
+
+**(Tang and Toennies)** J Chem Phys, 80, 3726 (1984).

doc/src/pair_mesocnt.rst

@@ -77,8 +77,11 @@ boron nitride nanotubes.
 
 .. note::
 
-   LAMMPS comes with one *mesocnt* style potential file
+   Because of their size, *mesocnt* style potential files
-   where the default number of data points per table is 1001.
+   are not bundled with LAMMPS.   When compiling LAMMPS from
+   source code, the file ``C_10_10.mesocnt`` should be downloaded
+   transparently from `https://download.lammps.org/potentials/C_10_10.mesocnt <https://download.lammps.org/potentials/C_10_10.mesocnt>`_
+   This file has as number of data points per table 1001.
    This is sufficient for NVT simulations. For proper energy
    conservation, we recommend using a potential file where
    the resolution for Phi is at least 2001 data points.

doc/src/pair_mesont_tpm.rst

@@ -147,12 +147,17 @@ where L is the maximum segment length, R is the maximum tube radius, and
 segments. Because of the use of extended chain concept at CNT ends, the recommended
 cutoff is 3L.
 
-The MESONT-TABTP_10_10.xrs potential file provided with LAMMPS (see the
+.. note::
-potentials directory) is parameterized for metal :doc:`units <units>`.
+
+   Because of their size, *mesont* style potential files
+   are not bundled with LAMMPS.   When compiling LAMMPS from
+   source code, the file ``TABTP_10_10.mesont`` should be downloaded
+   transparently from `https://download.lammps.org/potentials/TABTP_10_10.mesont <https://download.lammps.org/potentials/TABTP_10_10.mesont>`_
+
+The ``TABTP_10_10.mesont`` potential file is parameterized for metal :doc:`units <units>`.
 You can use the carbon nanotube mesoscopic force field with any LAMMPS units,
-but you would need to create your own TPMSSTP.xrs and TPMA.xrs potential files
+but you would need to create your own potential files with coefficients listed in
-with coefficients listed in appropriate units, if your simulation
+appropriate units, if your simulation does not use "metal" units.
-does not use "metal" units.
 
 The chirality parameters set during system generation must match the values
 specified during generation of the potential tables.

doc/src/pair_reaxc.rst

@@ -92,13 +92,11 @@ tested).
    create a suitable ReaxFF parameterization.
 
 The *cfile* setting can be specified as NULL, in which case default
-settings are used. A control file can be specified which defines
+settings are used. A control file can be specified which defines values
-values of control variables. Some control variables are
+of control variables. Some control variables are global parameters for
-global parameters for the ReaxFF potential. Others define certain
+the ReaxFF potential. Others define certain performance and output
-performance and output settings.
+settings.  Each line in the control file specifies the value for a
-Each line in the control file specifies the value for
+control variable.  The format of the control file is described below.
-a control variable.  The format of the control file is described
-below.
 
 .. note::
 
@@ -224,7 +222,10 @@ H, you would use the following pair_coeff command:
 
    pair_coeff * * ffield.reax C C N H
 
-----------
+-------------
+
+Control file
+""""""""""""
 
 The format of a line in the control file is as follows:
 
@@ -238,60 +239,73 @@ If the value of a control variable is not specified, then default
 values are used.  What follows is the list of variables along with a
 brief description of their use and default values.
 
-simulation_name: Output files produced by *pair_style reax/c* carry
-this name + extensions specific to their contents.  Partial energies
-are reported with a ".pot" extension, while the trajectory file has
-".trj" extension.
 
-tabulate_long_range: To improve performance, long range interactions
+*simulation_name*
-can optionally be tabulated (0 means no tabulation). Value of this
+   Output files produced by *pair_style reax/c* carry
-variable denotes the size of the long range interaction table.  The
+   this name + extensions specific to their contents.  Partial energies
-range from 0 to long range cutoff (defined in the *ffield* file) is
+   are reported with a ".pot" extension, while the trajectory file has
-divided into *tabulate_long_range* points.  Then at the start of
+   ".trj" extension.
-simulation, we fill in the entries of the long range interaction table
-by computing the energies and forces resulting from van der Waals and
-Coulomb interactions between every possible atom type pairs present in
-the input system.  During the simulation we consult to the long range
-interaction table to estimate the energy and forces between a pair of
-atoms. Linear interpolation is used for estimation. (default value =
-0)
 
-energy_update_freq: Denotes the frequency (in number of steps) of
+*tabulate_long_range*
-writes into the partial energies file. (default value = 0)
+   To improve performance, long range interactions can optionally be
+   tabulated (0 means no tabulation). Value of this variable denotes the
+   size of the long range interaction table.  The range from 0 to long
+   range cutoff (defined in the *ffield* file) is divided into
+   *tabulate_long_range* points.  Then at the start of simulation, we
+   fill in the entries of the long range interaction table by computing
+   the energies and forces resulting from van der Waals and Coulomb
+   interactions between every possible atom type pairs present in the
+   input system.  During the simulation we consult to the long range
+   interaction table to estimate the energy and forces between a pair of
+   atoms. Linear interpolation is used for estimation. (default value = 0)
 
-nbrhood_cutoff: Denotes the near neighbors cutoff (in Angstroms)
+*energy_update_freq*
-regarding the bonded interactions. (default value = 5.0)
+   Denotes the frequency (in number of steps) of writes into the partial
+   energies file. (default value = 0)
 
-hbond_cutoff: Denotes the cutoff distance (in Angstroms) for hydrogen
+*nbrhood_cutoff*
-bond interactions.(default value = 7.5. A value of 0.0 turns off
+   Denotes the near neighbors cutoff (in Angstroms)
-hydrogen bonds)
+   regarding the bonded interactions. (default value = 5.0)
 
-bond_graph_cutoff: is the threshold used in determining what is a
+*hbond_cutoff*
-physical bond, what is not. Bonds and angles reported in the
+   Denotes the cutoff distance (in Angstroms) for hydrogen
-trajectory file rely on this cutoff. (default value = 0.3)
+   bond interactions.(default value = 7.5. A value of 0.0 turns off
+   hydrogen bonds)
 
-thb_cutoff: cutoff value for the strength of bonds to be considered in
+*bond_graph_cutoff*
-three body interactions. (default value = 0.001)
+   is the threshold used in determining what is a
+   physical bond, what is not. Bonds and angles reported in the
+   trajectory file rely on this cutoff. (default value = 0.3)
 
-thb_cutoff_sq: cutoff value for the strength of bond order products
+*thb_cutoff*
-to be considered in three body interactions. (default value = 0.00001)
+   cutoff value for the strength of bonds to be considered in
+   three body interactions. (default value = 0.001)
 
-write_freq: Frequency of writes into the trajectory file. (default
+*thb_cutoff_sq*
-value = 0)
+   cutoff value for the strength of bond order products
+   to be considered in three body interactions. (default value = 0.00001)
 
-traj_title: Title of the trajectory - not the name of the trajectory
+*write_freq*
-file.
+   Frequency of writes into the trajectory file. (default
+   value = 0)
 
-atom_info: 1 means print only atomic positions + charge (default = 0)
+*traj_title*
+   Title of the trajectory - not the name of the trajectory file.
 
-atom_forces: 1 adds net forces to atom lines in the trajectory file
+*atom_info*
-(default = 0)
+   1 means print only atomic positions + charge (default = 0)
 
-atom_velocities: 1 adds atomic velocities to atoms line (default = 0)
+*atom_forces*
+   1 adds net forces to atom lines in the trajectory file (default = 0)
 
-bond_info: 1 prints bonds in the trajectory file (default = 0)
+*atom_velocities*
+   1 adds atomic velocities to atoms line (default = 0)
 
-angle_info: 1 prints angles in the trajectory file (default = 0)
+*bond_info*
+   1 prints bonds in the trajectory file (default = 0)
+
+*angle_info*
+   1 prints angles in the trajectory file (default = 0)
 
 ----------
 

doc/src/pair_resquared.rst

@@ -231,4 +231,4 @@ none
 
 .. _Babadi:
 
-**(Berardi)** Babadi, Ejtehadi, Everaers, J Comp Phys, 219, 770-779 (2006).
+**(Babadi)** Babadi, Ejtehadi, Everaers, J Comp Phys, 219, 770-779 (2006).

doc/src/pair_style.rst

@@ -144,6 +144,7 @@ accelerated styles exist.
 * :doc:`coul/slater/long <pair_coul>` - long-range smeared out Coulomb
 * :doc:`coul/shield <pair_coul_shield>` - Coulomb for boron nitride for use with :doc:`ilp/graphene/hbn <pair_ilp_graphene_hbn>` potential
 * :doc:`coul/streitz <pair_coul>` - Coulomb via Streitz/Mintmire Slater orbitals
+* :doc:`coul/tt <pair_coul_tt>` - damped charge-dipole Coulomb for Drude dipoles
 * :doc:`coul/wolf <pair_coul>` - Coulomb via Wolf potential
 * :doc:`coul/wolf/cs <pair_cs>` - Coulomb via Wolf potential with core/shell adjustments
 * :doc:`dpd <pair_dpd>` - dissipative particle dynamics (DPD)

doc/src/pg_lib_add.rst

@@ -1,33 +0,0 @@
-Adding code to the Library interface
-====================================
-
-The functionality of the LAMMPS library interface has historically
-always been motivated by the needs of its users and functions were
-added or expanded as they were needed and used.  Contributions to
-the interface are always welcome.  However with a refactoring of
-the library interface and its documentation that started in 2020,
-there are now a few requirements for inclusion of changes.
-
-  - New functions should be orthogonal to existing ones and not
-    implement functionality that can already be achieved with the
-    existing APIs.
-  - All changes and additions should be documented with
-    `Doxygen <https://doxygen.nl>`_ style comments and references
-    to those functions added to the corresponding files in the
-    ``doc/src`` folder.
-  - If possible, new unit tests to test those new features should
-    be added.
-  - The new feature should also be implemented and documented for
-    the Python and Fortran modules.
-  - All additions should work and be compatible with ``-DLAMMPS_BIGBIG``,
-    ``-DLAMMPS_SMALLBIG``, ``-DLAMMPS_SMALLSMALL`` and compiling
-    with and without MPI support.
-  - The ``library.h`` file should be kept compatible to C code at
-    a level similar to C89. Its interfaces may not reference any
-    custom data types (e.g. ``bigint``, ``tagint``, and so on) only
-    known inside of LAMMPS.
-  - only C style comments, not C++ style
-
-Please note, that these are *not* *strict* requirements, but the
-LAMMPS developers appreciate if they are followed closely and will
-assist with implementing what is missing.

doc/src/pg_lib_create.rst

@@ -1,104 +0,0 @@
-Creating or deleting a LAMMPS object
-====================================
-
-The :cpp:func:`lammps_open` and :cpp:func:`lammps_open_no_mpi`
-functions are used to create and initialize a
-:cpp:func:`LAMMPS` instance.  The calling program has to
-provide a handle where a reference to this instance can be stored and
-which has to be used in all subsequent function calls until that
-instance is destroyed by calling :cpp:func:`lammps_close`.
-Here is a simple example demonstrating its use:
-
-.. code-block:: C
-
-   #include "library.h"
-   #include <stdio.h>
-
-   int main(int argc, char **argv)
-   {
-     void *handle;
-     int version;
-     const char *lmpargv[] = { "liblammps", "-log", "none"};
-     int lmpargc = sizeof(lmpargv)/sizeof(const char *);
-
-     /* create LAMMPS instance */
-     handle = lammps_open_no_mpi(lmpargc, lmpargv, NULL);
-     if (handle == NULL) {
-       printf("LAMMPS initialization failed");
-       lammps_mpi_finalize();
-       return 1;
-     }
-
-     /* get and print numerical version code */
-     version = lammps_version(handle);
-     printf("LAMMPS Version: %d\n",version);
-
-     /* delete LAMMPS instance and shut down MPI */
-     lammps_close(handle);
-     lammps_mpi_finalize();
-     return 0;
-   }
-
-The LAMMPS library will be using the MPI library it was compiled with
-and will either run on all processors in the ``MPI_COMM_WORLD``
-communicator or on the set of processors in the communicator given in
-the ``comm`` argument of :cpp:func:`lammps_open`.  This means
-the calling code can run LAMMPS on all or a subset of processors.  For
-example, a wrapper code might decide to alternate between LAMMPS and
-another code, allowing them both to run on all the processors.  Or it
-might allocate part of the processors to LAMMPS and the rest to the
-other code by creating a custom communicator with ``MPI_Comm_split()``
-and running both codes concurrently before syncing them up periodically.
-Or it might instantiate multiple instances of LAMMPS to perform
-different calculations and either alternate between them, run them
-concurrently on split communicators, or run them one after the other.
-The :cpp:func:`lammps_open` function may be called multiple
-times for this latter purpose.
-
-The :cpp:func:`lammps_close` function is used to shut down
-the :cpp:class:`LAMMPS <LAMMPS_NS::LAMMPS>` class pointed to by the handle
-passed as an argument and free all its memory. This has to be called for
-every instance created with any of the :cpp:func:`lammps_open` functions.  It will, however, **not** call
-``MPI_Finalize()``, since that may only be called once.  See
-:cpp:func:`lammps_mpi_finalize` for an alternative to calling
-``MPI_Finalize()`` explicitly in the calling program.
-
-The :cpp:func:`lammps_free` function is a clean-up
-function to free memory that the library allocated previously
-via other function calls.  See below for notes in the descriptions
-of the individual commands where such memory buffers were allocated.
-
------------------------
-
-.. doxygenfunction:: lammps_open
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_open_no_mpi
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_open_fortran
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_close
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_mpi_init
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_mpi_finalize
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_free
-   :project: progguide

doc/src/pg_lib_properties.rst

@@ -1,111 +0,0 @@
-Retrieving or setting LAMMPS system properties
-==============================================
-
-The library interface allows to extract different kinds of information
-about the active simulation instance and also to modify some of it.
-This enables combining MD simulation steps with other processing and
-simulation methods computed in the calling code or another code that is
-coupled to LAMMPS via the library interface.  In some cases the data
-returned is direct reference to the original data inside LAMMPS cast
-to a void pointer.  In that case the data needs to be cast to a suitable
-pointer to be able to access it, and you need to know the correct dimensions
-and lengths.  When accessing per-atom data, please note that this data
-is the per-processor **local** data and indexed accordingly. These arrays
-can change sizes and order at every neighbor list rebuild and atom sort
-event as atoms are migrating between sub-domains.
-
-.. code-block:: C
-
-   #include "library.h"
-   #include <stdio.h>
-
-   int main(int argc, char **argv)
-   {
-     void *handle;
-     int i;
-
-     handle = lammps_open_no_mpi(0, NULL, NULL);
-     lammps_file(handle,"in.sysinit");
-     printf("running simulation with %g atoms\n",
-            lammps_get_natoms(handle));
-
-     lammps_command(handle,"run 1000 post no");
-
-     for (i=0; i < 10; ++i) {
-       lammps_command(handle,"run 100 pre no post no");
-       printf("PE = %g\nKE = %g\n",
-              lammps_get_thermo(handle,"pe"),
-              lammps_get_thermo(handle,"ke"));
-     }
-     lammps_close(handle);
-     return 0;
-   }
-
-
------------------------
-
-.. doxygenfunction:: lammps_version
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_memory_usage
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_get_mpi_comm
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_get_natoms
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_get_thermo
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_extract_box
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_reset_box
-   :project: progguide
-
--------------------
-
-.. doxygenfunction:: lammps_extract_setting
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_extract_global_datatype
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_extract_global
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_extract_atom_datatype
-   :project: progguide
-
-
------------------------
-
-.. doxygenfunction:: lammps_extract_atom
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_create_atoms(void *handle, int n, int *id, int *type, double *x, double *v, int *image, int bexpand)
-   :project: progguide
-
-

doc/src/pg_lib_scatter.rst

@@ -1,29 +0,0 @@
-Library functions for scatter/gather operations
-================================================
-
-.. TODO add description
-
------------------------
-
-.. doxygenfunction:: lammps_gather_atoms
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_gather_atoms_concat
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_gather_atoms_subset
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_scatter_atoms
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_scatter_atoms_subset
-   :project: progguide

doc/src/pg_lib_utility.rst

@@ -1,30 +0,0 @@
-Library interface utility functions
-===================================
-
-To simplify some of the tasks, the library interface contains
-some utility functions that are not directly calling LAMMPS.
-
------------------------
-
-.. doxygenfunction:: lammps_encode_image_flags
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_decode_image_flags(int image, int *flags)
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_set_fix_external_callback(void *, char *, FixExternalFnPtr, void*)
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_has_error
-   :project: progguide
-
------------------------
-
-.. doxygenfunction:: lammps_get_last_error_message
-   :project: progguide

doc/src/pg_library.rst

@@ -1,158 +0,0 @@
-LAMMPS Library Interfaces
-*************************
-
-As described on the :doc:`library interface to LAMMPS <Howto_library>`
-doc page, LAMMPS can be built as a library (static or shared), 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
-script <Python_head>`.  Even the LAMMPS standalone executable is
-essentially a thin wrapper on top of the LAMMPS library, creating a
-LAMMPS instance, processing input and then existing.
-
-Several of these approaches are based on C language wrapper functions
-in the files ``src/library.h`` and ``src/library.cpp``, but it is also
-possible to use C++ directly.  The basic procedure is always the same:
-you create one or more instances of the
-:cpp:class:`LAMMPS <LAMMPS_NS::LAMMPS>` and then pass commands as
-strings or from files to that LAMMPS instance to execute calculations,
-or read, manipulate, and update data from the active class instances
-inside the LAMMPS to do analysis or perform operations that are not
-possible with existing commands.
-
-.. _thread-safety:
-
-.. admonition:: Thread-safety
-   :class: note
-
-   LAMMPS was initially not 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).
-
-   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.
-
-----------
-
-.. _lammps_c_api:
-
-LAMMPS C Library API
-====================
-
-The C library interface is most commonly used path to manage LAMMPS
-instances from a compiled code and it is the basis for the :doc:`Python
-<pg_python>` and :doc:`Fortran <pg_fortran>` modules.  Almost all
-functions of the C language API require an argument containing a
-"handle" in the form of a ``void *`` type variable, which points to the
-location of a LAMMPS class instance.
-
-The ``library.h`` header file by default includes the ``mpi.h`` header
-for an MPI library, so it must be present when compiling code using the
-library interface.  This usually must be the header from the same MPI
-library as the LAMMPS library was compiled with.  The exception is when
-LAMMPS was compiled in serial mode using the ``STUBS`` MPI library.  In
-that case the calling code may be compiled with a different MPI library
-for as long as :cpp:func:`lammps_open_no_mpi` is called to create a
-LAMMPS instance. Then you may set the define ``-DLAMMPS_LIB_NO_MPI``
-when compiling your code and the inclusion of ``mpi.h`` will be skipped
-and consequently the function :cpp:func:`lammps_open` may not be used.
-
-.. admonition:: Errors versus exceptions
-   :class: note
-
-   If any of the function calls in the LAMMPS library API will trigger
-   an error inside LAMMPS, this will result in an abort of the entire
-   program.  This is not always desirable.  Instead, LAMMPS can be
-   compiled to instead :ref:`throw a C++ exception <exceptions>`.
-
-.. warning::
-
-   No checks are made on the arguments of the function calls of the C
-   library interface.  *All* function arguments must be non-NULL unless
-   *explicitly* allowed and point to consistent and valid data.  Buffers
-   for storing returned data must be allocated to a suitable size.
-   Passing invalid or unsuitable information will likely cause crashes
-   or corrupt data.
-
-------------------------------
-
-.. toctree::
-   :maxdepth: 1
-
-   pg_lib_create
-   pg_lib_execute
-   pg_lib_properties
-   pg_lib_objects
-   pg_lib_scatter
-   pg_lib_neighbor
-   pg_lib_config
-   pg_lib_utility
-   pg_lib_add
-
---------------------
-
-.. _lammps_python_api:
-
-LAMMPS Python APIs
-==================
-
-The LAMMPS Python module enables calling the LAMMPS C library API from
-Python by dynamically loading functions in the LAMMPS shared library through
-the `Python ctypes module <https://docs.python.org/3/library/ctypes.html>`_.
-Because of the dynamic loading, it is **required** that LAMMPS is compiled
-in :ref:`"shared" mode <exe>`.  The Python interface is object oriented, but
-otherwise trying to be very similar to the C library API.  Three different
-Python classes to run LAMMPS are available and they build on each other.
-
-.. toctree::
-   :maxdepth: 1
-
-   pg_python
-
--------------------
-
-.. _lammps_fortran_api:
-
-LAMMPS Fortran API
-==================
-
-The LAMMPS Fortran module is a wrapper around calling functions from the
-LAMMPS C library API from Fortran through the ISO_C_BINDING feature in
-Fortran 2003.  The interface is object oriented but otherwise trying to
-be very similar to the C library API and the basic Python module.
-
-.. toctree::
-   :maxdepth: 1
-
-   pg_fortran
-
--------------------
-
-.. _lammps_cplusplus_api:
-
-LAMMPS C++ API
-==============
-
-It is also possible to invoke the LAMMPS C++ API directly in your code.
-It is lacking some of the convenience of the C library API, but it allows
-a more direct access to simulation data and thus more low-level manipulations.
-The following links provide some examples and references to the C++ API.
-
-.. toctree::
-   :maxdepth: 1
-
-   pg_cplusplus
-
-