diff --git a/SECURITY.md b/SECURITY.md
index f06b781d11..7b0ed1f560 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -14,14 +14,14 @@ and tested by the LAMMPS developers, so it is easy to import bad
behavior from calling functions in one of those libraries.
Thus is is quite easy to crash LAMMPS through malicious input and do all
-kinds of filesystem manipulations. And because of that LAMMPS should
+kinds of file system manipulations. And because of that LAMMPS should
**NEVER** be compiled or **run** as superuser, either from a "root" or
"administrator" account directly or indirectly via "sudo" or "su".
Therefore what could be seen as a security vulnerability is usually
-either a user mistake or a bug in the code. Bugs can be reported in
-the LAMMPS project
-[issue tracker on GitHub](https://github.com/lammps/lammps/issues).
+either a user mistake or a bug in the code. Bugs can be reported in the
+LAMMPS project [issue tracker on
+GitHub](https://github.com/lammps/lammps/issues).
To mitigate issues with using homoglyphs or bidirectional reordering in
unicode, which have been demonstrated as a vector to obfuscate and hide
@@ -30,10 +30,18 @@ for unicode characters and only all-ASCII source code is accepted.
# Version Updates
-LAMMPS follows continuous release development model. We aim to keep all
-release versions (stable or patch) fully functional and employ a variety
-of automatic testing procedures to detect failures of existing
-functionality from adding new features before releases are made. Thus
-bugfixes and updates are only integrated into the current development
-branch and thus the next (patch) release and users are recommended to
-update regularly.
+LAMMPS follows continuous release development model. We aim to keep to
+keep the development version (develop branch) always fully functional
+and employ a variety of automatic testing procedures to detect failures
+of existing functionality from adding or modifying features. Most of
+those tests are run on pull requests *before* merging to the development
+branch. The develop branch is protected, so all changes *must* be
+submitted as a pull request and thus cannot avoid the automated tests.
+
+Additional tests are run *after* merging. Before releases are made
+*all* tests must have cleared. Then a release tag is applied and the
+release branch fast-forwarded to that tag. Bug fixes and updates are
+applied to the current development branch and thus will be available in
+the next (patch) release. For stable releases, selected bug fixes are
+back-ported and occasionally published as update releases. There are
+only updates to the latest stable release.
diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt
index aaa0885072..28c3d6c027 100644
--- a/cmake/CMakeLists.txt
+++ b/cmake/CMakeLists.txt
@@ -376,6 +376,7 @@ pkg_depends(DIELECTRIC EXTRA-PAIR)
pkg_depends(CG-DNA MOLECULE)
pkg_depends(CG-DNA ASPHERE)
pkg_depends(ELECTRODE KSPACE)
+pkg_depends(EXTRA-MOLECULE MOLECULE)
# detect if we may enable OpenMP support by default
set(BUILD_OMP_DEFAULT OFF)
diff --git a/cmake/Modules/Packages/MDI.cmake b/cmake/Modules/Packages/MDI.cmake
index d873c8f6d1..edae4ffcbd 100644
--- a/cmake/Modules/Packages/MDI.cmake
+++ b/cmake/Modules/Packages/MDI.cmake
@@ -8,8 +8,8 @@ option(DOWNLOAD_MDI "Download and compile the MDI library instead of using an al
if(DOWNLOAD_MDI)
message(STATUS "MDI download requested - we will build our own")
- set(MDI_URL "https://github.com/MolSSI-MDI/MDI_Library/archive/v1.4.1.tar.gz" CACHE STRING "URL for MDI tarball")
- set(MDI_MD5 "f9505fccd4c79301a619f6452dad4ad9" CACHE STRING "MD5 checksum for MDI tarball")
+ set(MDI_URL "https://github.com/MolSSI-MDI/MDI_Library/archive/v1.4.12.tar.gz" CACHE STRING "URL for MDI tarball")
+ set(MDI_MD5 "7a222353ae8e03961d5365e6cd48baee" CACHE STRING "MD5 checksum for MDI tarball")
mark_as_advanced(MDI_URL)
mark_as_advanced(MDI_MD5)
enable_language(C)
diff --git a/cmake/Modules/Packages/ML-IAP.cmake b/cmake/Modules/Packages/ML-IAP.cmake
index 63f91ba8d3..0e711cde8f 100644
--- a/cmake/Modules/Packages/ML-IAP.cmake
+++ b/cmake/Modules/Packages/ML-IAP.cmake
@@ -25,16 +25,18 @@ if(MLIAP_ENABLE_PYTHON)
endif()
set(MLIAP_BINARY_DIR ${CMAKE_BINARY_DIR}/cython)
- set(MLIAP_CYTHON_SRC ${LAMMPS_SOURCE_DIR}/ML-IAP/mliap_model_python_couple.pyx)
- get_filename_component(MLIAP_CYTHON_BASE ${MLIAP_CYTHON_SRC} NAME_WE)
+ file(GLOB MLIAP_CYTHON_SRC ${LAMMPS_SOURCE_DIR}/ML-IAP/*.pyx)
file(MAKE_DIRECTORY ${MLIAP_BINARY_DIR})
- add_custom_command(OUTPUT ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.cpp ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.h
- COMMAND ${CMAKE_COMMAND} -E copy_if_different ${MLIAP_CYTHON_SRC} ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.pyx
- COMMAND ${Cythonize_EXECUTABLE} -3 ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.pyx
- WORKING_DIRECTORY ${MLIAP_BINARY_DIR}
- MAIN_DEPENDENCY ${MLIAP_CYTHON_SRC}
- COMMENT "Generating C++ sources with cythonize...")
+ foreach(MLIAP_CYTHON_FILE ${MLIAP_CYTHON_SRC})
+ get_filename_component(MLIAP_CYTHON_BASE ${MLIAP_CYTHON_FILE} NAME_WE)
+ add_custom_command(OUTPUT ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.cpp ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.h
+ COMMAND ${CMAKE_COMMAND} -E copy_if_different ${MLIAP_CYTHON_FILE} ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.pyx
+ COMMAND ${Cythonize_EXECUTABLE} -3 ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.pyx
+ WORKING_DIRECTORY ${MLIAP_BINARY_DIR}
+ MAIN_DEPENDENCY ${MLIAP_CYTHON_FILE}
+ COMMENT "Generating C++ sources with cythonize...")
+ target_sources(lammps PRIVATE ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.cpp)
+ endforeach()
target_compile_definitions(lammps PRIVATE -DMLIAP_PYTHON)
- target_sources(lammps PRIVATE ${MLIAP_BINARY_DIR}/${MLIAP_CYTHON_BASE}.cpp)
target_include_directories(lammps PRIVATE ${MLIAP_BINARY_DIR})
endif()
diff --git a/cmake/presets/clang.cmake b/cmake/presets/clang.cmake
index a0d654ad35..f1964f3e0f 100644
--- a/cmake/presets/clang.cmake
+++ b/cmake/presets/clang.cmake
@@ -3,6 +3,13 @@
# prefer flang over gfortran, if available
find_program(CLANG_FORTRAN NAMES flang gfortran f95)
set(ENV{OMPI_FC} ${CLANG_FORTRAN})
+get_filename_component(_tmp_fc ${CLANG_FORTRAN} NAME)
+if (_tmp_fc STREQUAL "flang")
+ set(FC_STD_VERSION "-std=f2018")
+ set(BUILD_MPI OFF)
+else()
+ set(FC_STD_VERSION "-std=f2003")
+endif()
set(CMAKE_CXX_COMPILER "clang++" CACHE STRING "" FORCE)
set(CMAKE_C_COMPILER "clang" CACHE STRING "" FORCE)
@@ -10,9 +17,9 @@ set(CMAKE_Fortran_COMPILER ${CLANG_FORTRAN} CACHE STRING "" FORCE)
set(CMAKE_CXX_FLAGS_DEBUG "-Wall -Wextra -g" CACHE STRING "" FORCE)
set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "-Wall -Wextra -g -O2 -DNDEBUG" CACHE STRING "" FORCE)
set(CMAKE_CXX_FLAGS_RELEASE "-O3 -DNDEBUG" CACHE STRING "" FORCE)
-set(CMAKE_Fortran_FLAGS_DEBUG "-Wall -Wextra -g -std=f2003" CACHE STRING "" FORCE)
-set(CMAKE_Fortran_FLAGS_RELWITHDEBINFO "-Wall -Wextra -g -O2 -DNDEBUG -std=f2003" CACHE STRING "" FORCE)
-set(CMAKE_Fortran_FLAGS_RELEASE "-O3 -DNDEBUG -std=f2003" CACHE STRING "" FORCE)
+set(CMAKE_Fortran_FLAGS_DEBUG "-Wall -Wextra -g ${FC_STD_VERSION}" CACHE STRING "" FORCE)
+set(CMAKE_Fortran_FLAGS_RELWITHDEBINFO "-Wall -Wextra -g -O2 -DNDEBUG ${FC_STD_VERSION}" CACHE STRING "" FORCE)
+set(CMAKE_Fortran_FLAGS_RELEASE "-O3 -DNDEBUG ${FC_STD_VERSION}" CACHE STRING "" FORCE)
set(CMAKE_C_FLAGS_DEBUG "-Wall -Wextra -g" CACHE STRING "" FORCE)
set(CMAKE_C_FLAGS_RELWITHDEBINFO "-Wall -Wextra -g -O2 -DNDEBUG" CACHE STRING "" FORCE)
set(CMAKE_C_FLAGS_RELEASE "-O3 -DNDEBUG" CACHE STRING "" FORCE)
diff --git a/doc/lammps.1 b/doc/lammps.1
index f1a3d0f2f9..e4f0f2a9eb 100644
--- a/doc/lammps.1
+++ b/doc/lammps.1
@@ -1,7 +1,7 @@
-.TH LAMMPS "1" "3 August 2022" "2022-8-3"
+.TH LAMMPS "1" "15 September 2022" "2022-9-15"
.SH NAME
.B LAMMPS
-\- Molecular Dynamics Simulator. Version 3 August 2022
+\- Molecular Dynamics Simulator. Version 15 September 2022
.SH SYNOPSIS
.B lmp
diff --git a/doc/src/Bibliography.rst b/doc/src/Bibliography.rst
index 9f3591dcde..2d27d2e6f9 100644
--- a/doc/src/Bibliography.rst
+++ b/doc/src/Bibliography.rst
@@ -314,7 +314,7 @@ Bibliography
Espanol, Revenga, Physical Review E, 67, 026705 (2003).
**(Espanol1997)**
- Espanol, Europhys Lett, 40(6): 631-636 (1997). DOI: 10.1209/epl/i1997-00515-8
+ Espanol, Europhys Lett, 40(6): 631-636 (1997). DOI:10.1209/epl/i1997-00515-8
**(Evans and Morriss)**
Evans and Morriss, Phys Rev A, 30, 1528 (1984).
@@ -368,7 +368,7 @@ Bibliography
Frenkel and Smit, Understanding Molecular Simulation, Academic Press, London, 2002.
**(GLE4MD)**
- `http://gle4md.org/ `_
+ `https://ipi-code.org/ `_ to
+See `Obtaining KIM Models `_ to
learn how to install a pre-build binary of the OpenKIM Repository of Models.
See the list of all KIM models here: https://openkim.org/browse/models
@@ -432,7 +432,7 @@ Enabling the extra unit tests have some requirements,
``EAM_Dynamo_MendelevAckland_2007v3_Zr__MO_004835508849_000``,
``EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005``, and
``LennardJones612_UniversalShifted__MO_959249795837_003`` KIM models.
- See `Obtaining KIM Models `_
+ See `Obtaining KIM Models `_
to learn how to install a pre-built binary of the OpenKIM Repository of
Models or see
`Installing KIM Models `_
@@ -1053,7 +1053,7 @@ VORONOI package
-----------------------------
To build with this package, you must download and build the
-`Voro++ library `_ or install a
+`Voro++ library `_ or install a
binary package provided by your operating system.
.. tabs::
diff --git a/doc/src/Build_manual.rst b/doc/src/Build_manual.rst
index d91ac94be5..1ef0a80549 100644
--- a/doc/src/Build_manual.rst
+++ b/doc/src/Build_manual.rst
@@ -176,7 +176,7 @@ math expressions transparently into embedded images.
For converting the generated ePUB file to a MOBI format file (for e-book
readers, like Kindle, that cannot read ePUB), you also need to have the
``ebook-convert`` tool from the "calibre" software
-installed. `http://calibre-ebook.com/ `_ is included in the LAMMPS
-distribution. It is portable across all platforms. Depending on the size
-of the FFTs and the number of processors used, the other libraries listed
-here can be faster.
+The `KISS FFT library `_ is
+included in the LAMMPS distribution. It is portable across all
+platforms. Depending on the size of the FFTs and the number of
+processors used, the other libraries listed here can be faster.
However, note that long-range Coulombics are only a portion of the
-per-timestep CPU cost, FFTs are only a portion of long-range
-Coulombics, and 1d FFTs are only a portion of the FFT cost (parallel
-communication can be costly). A breakdown of these timings is printed
-to the screen at the end of a run when using the
-:doc:`kspace_style pppm ` command. The
-:doc:`Screen and logfile output `
-page gives more details. A more detailed (and time consuming)
-report of the FFT performance is generated with the
+per-timestep CPU cost, FFTs are only a portion of long-range Coulombics,
+and 1d FFTs are only a portion of the FFT cost (parallel communication
+can be costly). A breakdown of these timings is printed to the screen
+at the end of a run when using the :doc:`kspace_style pppm
+` command. The :doc:`Screen and logfile output
+` page gives more details. A more detailed (and time
+consuming) report of the FFT performance is generated with the
:doc:`kspace_modify fftbench yes ` command.
FFTW is a fast, portable FFT library that should also work on any
-platform and can be faster than the KISS FFT library. You can
-download it from `www.fftw.org `_. LAMMPS requires
-version 3.X; the legacy version 2.1.X is no longer supported.
+platform and can be faster than the KISS FFT library. You can download
+it from `www.fftw.org `_. LAMMPS requires version
+3.X; the legacy version 2.1.X is no longer supported.
Building FFTW for your box should be as simple as ``./configure; make;
make install``. The install command typically requires root privileges
diff --git a/doc/src/Commands_all.rst b/doc/src/Commands_all.rst
index 5e309c3ed0..d7b1609619 100644
--- a/doc/src/Commands_all.rst
+++ b/doc/src/Commands_all.rst
@@ -15,7 +15,9 @@
General commands
================
-An alphabetic list of general LAMMPS commands.
+An alphabetic list of general LAMMPS commands. Note that style
+commands with many variants, can be more easily accessed via the small
+table above.
.. table_from_list::
:columns: 5
@@ -61,6 +63,7 @@ An alphabetic list of general LAMMPS commands.
* :doc:`kspace_modify `
* :doc:`kspace_style `
* :doc:`label `
+ * :doc:`labelmap `
* :doc:`lattice `
* :doc:`log `
* :doc:`mass `
diff --git a/doc/src/Commands_fix.rst b/doc/src/Commands_fix.rst
index cb61cbe17b..c5c2fb7cba 100644
--- a/doc/src/Commands_fix.rst
+++ b/doc/src/Commands_fix.rst
@@ -165,6 +165,7 @@ OPT.
* :doc:`orient/fcc `
* :doc:`orient/eco `
* :doc:`pafi `
+ * :doc:`pair `
* :doc:`phonon `
* :doc:`pimd `
* :doc:`planeforce `
diff --git a/doc/src/Developer_updating.rst b/doc/src/Developer_updating.rst
index c4831d8db7..091312d68e 100644
--- a/doc/src/Developer_updating.rst
+++ b/doc/src/Developer_updating.rst
@@ -328,7 +328,7 @@ removed so this update is **required** to avoid compilation failure.
Split of fix STORE into fix STORE/GLOBAL and fix STORE/PERATOM
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. versionchanged:: TBD
+.. versionchanged:: 15Sep2022
This change splits the GLOBAL and PERATOM modes of fix STORE into two
separate fixes STORE/GLOBAL and STORE/PERATOM. There was very little
@@ -387,7 +387,7 @@ This change is **required** or else the code will not compile.
Use Output::get_dump_by_id() instead of Output::find_dump()
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. versionchanged:: TBD
+.. versionchanged:: 15Sep2022
The accessor function to individual dump style instances has been changed
from ``Output::find_dump()`` returning the index of the dump instance in
diff --git a/doc/src/Developer_utils.rst b/doc/src/Developer_utils.rst
index e1a5f7741d..b92d817d87 100644
--- a/doc/src/Developer_utils.rst
+++ b/doc/src/Developer_utils.rst
@@ -175,6 +175,12 @@ and parsing files or arguments.
.. doxygenfunction:: is_double
:project: progguide
+.. doxygenfunction:: is_id
+ :project: progguide
+
+.. doxygenfunction:: is_type
+ :project: progguide
+
Potential file functions
^^^^^^^^^^^^^^^^^^^^^^^^
@@ -205,6 +211,9 @@ Argument processing
.. doxygenfunction:: expand_args
:project: progguide
+.. doxygenfunction:: expand_type
+ :project: progguide
+
Convenience functions
^^^^^^^^^^^^^^^^^^^^^
diff --git a/doc/src/Errors_debug.rst b/doc/src/Errors_debug.rst
index 786a21ecae..787f3f6b34 100644
--- a/doc/src/Errors_debug.rst
+++ b/doc/src/Errors_debug.rst
@@ -75,7 +75,7 @@ Using the GDB debugger to get a stack trace
There are two options to use the GDB debugger for identifying the origin
of the segmentation fault or similar crash. The GDB debugger has many
more features and options, as can be seen for example its `online
-documentation `
Mass command must set a type from 1-N where N is the number of atom
types.
+*Invalid label2type() function syntax in variable formula*
+ The first argument must be a label map kind (atom, bond, angle,
+ dihedral, or improper) and the second argument must be a valid type
+ label that has been assigned to a numeric type.
+
*Invalid use of library file() function*
This function is called through the library interface. This
error should not occur. Contact the developers if it does.
@@ -5585,9 +5590,18 @@ Doc page with :doc:`WARNING messages `
*LJ6 off not supported in pair_style buck/long/coul/long*
Self-explanatory.
+*Label map is incomplete: all types must be assigned a unique type label*
+ For a given type-kind (atom types, bond types, etc.) to be written to
+ the data file, all associated types must be assigned a type label, and
+ each type label can be assigned to only one numeric type.
+
*Label wasn't found in input script*
Self-explanatory.
+*Labelmap command before simulation box is defined*
+ The labelmap command cannot be used before a read_data,
+ read_restart, or create_box command.
+
*Lattice orient vectors are not orthogonal*
The three specified lattice orientation vectors must be mutually
orthogonal.
@@ -5863,6 +5877,12 @@ Doc page with :doc:`WARNING messages `
*Must not have multiple fixes change box parameter ...*
Self-explanatory.
+*Must read Angle Type Labels before Angles*
+ An Angle Type Labels section of a data file must come before the Angles section.
+
+*Must read Atom Type Labels before Atoms*
+ An Atom Type Labels section of a data file must come before the Atoms section.
+
*Must read Atoms before Angles*
The Atoms section of a data file must come before an Angles section.
@@ -5893,6 +5913,15 @@ Doc page with :doc:`WARNING messages `
The Atoms section of a data file must come before a Velocities
section.
+*Must read Bond Type Labels before Bonds*
+ A Bond Type Labels section of a data file must come before the Bonds section.
+
+*Must read Dihedral Type Labels before Dihedrals*
+ An Dihedral Type Labels section of a data file must come before the Dihedrals section.
+
+*Must read Improper Type Labels before Impropers*
+ An Improper Type Labels section of a data file must come before the Impropers section.
+
*Must re-specify non-restarted pair style (xxx) after read_restart*
For pair styles, that do not store their settings in a restart file,
it must be defined with a new 'pair_style' command after read_restart.
@@ -7849,6 +7878,10 @@ keyword to allow for additional bonds to be formed
Number of local atoms times number of columns must fit in a 32-bit
integer for dump.
+*Topology type exceeds system topology type*
+ The number of bond, angle, etc types exceeds the system setting. See
+ the create_box or read_data command for how to specify these values.
+
*Tree structure in joint connections*
Fix poems cannot (yet) work with coupled bodies whose joints connect
the bodies in a tree structure.
@@ -7873,6 +7906,13 @@ keyword to allow for additional bonds to be formed
*Two groups cannot be the same in fix spring couple*
Self-explanatory.
+*The %s type label %s is already in use for type %s*
+ For a given type-kind (atom types, bond types, etc.), a given type
+ label can be assigned to only one numeric type.
+
+*Type label string %s for %s type %s is invalid*
+ See the labelmap command documentation for valid type labels.
+
*Unable to initialize accelerator for use*
There was a problem initializing an accelerator for the gpu package
diff --git a/doc/src/Fortran.rst b/doc/src/Fortran.rst
index dd848a812e..77ab447c7c 100644
--- a/doc/src/Fortran.rst
+++ b/doc/src/Fortran.rst
@@ -3,7 +3,9 @@ The ``LIBLAMMPS`` Fortran Module
The ``LIBLAMMPS`` module provides an interface to call LAMMPS from a
Fortran code. It is based on the LAMMPS C-library interface and
-requires a Fortran 2003 compatible compiler to be compiled.
+requires a Fortran 2003 compatible compiler to be compiled. It is
+designed to be self-contained and not require any support functions
+written in C, C++, or Fortran.
While C libraries have a defined binary interface (ABI) and can thus be
used from multiple compiler versions from different vendors for as long
@@ -19,12 +21,20 @@ for a simple program using the Fortran interface would be:
mpifort -o testlib.x lammps.f90 testlib.f90 -L. -llammps
Please note, that the MPI compiler wrapper is only required when the
-calling the library from an MPI parallel code. Please also note the
-order of the source files: the ``lammps.f90`` file needs to be compiled
-first, since it provides the ``LIBLAMMPS`` module that is imported by
-the Fortran code using the interface. A working example code can be
-found together with equivalent examples in C and C++ in the
-``examples/COUPLE/simple`` folder of the LAMMPS distribution.
+calling the library from an MPI parallel code. Otherwise, using the
+fortran compiler (gfortran, ifort, flang, etc.) will suffice. It may be
+necessary to link to additional libraries depending on how LAMMPS was
+configured and whether the LAMMPS library :doc:`was compiled as a static
+or shared library `.
+
+If the LAMMPS library itself has been compiled with MPI support, the
+resulting executable will still be able to run LAMMPS in parallel with
+``mpirun`` or equivalent. Please also note that the order of the source
+files matters: 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. A working example code can be found together
+with equivalent examples in C and C++ in the ``examples/COUPLE/simple``
+folder of the LAMMPS distribution.
.. versionadded:: 9Oct2020
@@ -49,17 +59,18 @@ found together with equivalent examples in C and C++ in the
Creating or deleting a LAMMPS object
************************************
-With the Fortran interface the creation of a :cpp:class:`LAMMPS
+With the Fortran interface, the creation of a :cpp:class:`LAMMPS
` instance is included in the constructor for
creating the :f:func:`lammps` derived type. To import the definition of
-that type and its type bound procedures you need to add a ``USE
+that type and its type bound procedures, you need to add a ``USE
LIBLAMMPS`` statement. Internally it will call either
:cpp:func:`lammps_open_fortran` or :cpp:func:`lammps_open_no_mpi` from
the C library API to create the class instance. All arguments are
optional and :cpp:func:`lammps_mpi_init` will be called automatically,
-if it is needed. Similarly, a possible call to :cpp:func:`lammps_finalize`
-is integrated into the :f:func:`close` function and triggered with
-the optional logical argument set to ``.true.``. Here is a simple example:
+if it is needed. Similarly, a possible call to
+:cpp:func:`lammps_mpi_finalize` is integrated into the :f:func:`close`
+function and triggered with the optional logical argument set to
+``.true.``. Here is a simple example:
.. code-block:: fortran
@@ -80,11 +91,11 @@ the optional logical argument set to ``.true.``. Here is a simple example:
END PROGRAM testlib
It is also possible to pass command line flags from Fortran to C/C++ and
-thus make the resulting executable behave similar to the standalone
-executable (it will ignore the `-in/-i` flag, though). This allows to
-use the command line to configure accelerator and suffix settings,
+thus make the resulting executable behave similarly to the standalone
+executable (it will ignore the `-in/-i` flag, though). This allows
+using the command line to configure accelerator and suffix settings,
configure screen and logfile output, or to set index style variables
-from the command line and more. Here is a correspondingly adapted
+from the command line and more. Here is a correspondingly adapted
version of the previous example:
.. code-block:: fortran
@@ -117,13 +128,13 @@ version of the previous example:
--------------------
Executing LAMMPS commands
-=========================
+*************************
Once a LAMMPS instance is created, it is possible to "drive" the LAMMPS
-simulation by telling LAMMPS to read commands from a file, or pass
+simulation by telling LAMMPS to read commands from a file or to pass
individual or multiple commands from strings or lists of strings. This
-is done similar to how it is implemented in the `C-library
-` interface. Before handing off the calls to the
+is done similarly to how it is implemented in the :doc:`C-library
+interface `. Before handing off the calls to the
C-library interface, the corresponding Fortran versions of the calls
(:f:func:`file`, :f:func:`command`, :f:func:`commands_list`, and
:f:func:`commands_string`) have to make a copy of the strings passed as
@@ -165,6 +176,57 @@ Below is a small demonstration of the uses of the different functions:
---------------
+Accessing system properties
+***************************
+
+The C-library interface allows the :doc:`extraction of different kinds
+of information ` about the active simulation
+instance and also - in some cases - to apply modifications to it. In
+some cases, the C-library interface makes pointers to internal data
+structures accessible, thus when accessing them from Fortran, special
+care is needed to avoid data corruption and crashes. Thus please see
+the documentation of the individual type bound procedures for details.
+
+Below is an example demonstrating some of the possible uses.
+
+.. code-block:: fortran
+
+ PROGRAM testprop
+ USE LIBLAMMPS
+ USE, INTRINSIC :: ISO_C_BINDING, ONLY : c_double, c_int64_t
+ TYPE(lammps) :: lmp
+ INTEGER(kind=8) :: natoms
+ REAL(c_double), POINTER :: dt
+ INTEGER(c_int64_t), POINTER :: ntimestep
+ REAL(kind=8) :: pe, ke
+
+ lmp = lammps()
+ CALL lmp%file('in.sysinit')
+ natoms = INT(lmp%get_natoms(),8)
+ WRITE(6,'(A,I8,A)') 'Running a simulation with', natoms, ' atoms'
+ WRITE(6,'(I8,A,I8,A,I3,A)') lmp%extract_setting('nlocal'), ' local and', &
+ lmp%extract_setting('nghost'), ' ghost atom. ', &
+ lmp%extract_setting('ntypes'), ' atom types'
+
+ CALL lmp%command('run 2 post no')
+ dt = lmp%extract_global('dt')
+ ntimestep = lmp%extract_global('ntimestep')
+ WRITE(6,'(A,I4,A,F4.1,A)') 'At step:', ntimestep, ' Changing timestep from', dt, ' to 0.5'
+ dt = 0.5
+ CALL lmp%command('run 2 post no')
+
+ WRITE(6,'(A,I4)') 'At step:', ntimestep
+ pe = lmp%get_thermo('pe')
+ ke = lmp%get_thermo('ke')
+ PRINT*, 'PE = ', pe
+ PRINT*, 'KE = ', ke
+
+ CALL lmp%close(.TRUE.)
+
+ END PROGRAM testprop
+
+---------------
+
The ``LIBLAMMPS`` module API
****************************
@@ -178,14 +240,24 @@ of the contents of the ``LIBLAMMPS`` Fortran interface to LAMMPS.
class instance that any of the included calls are forwarded to.
:f c_ptr handle: reference to the LAMMPS class
- :f close: :f:func:`close`
- :f version: :f:func:`version`
- :f file: :f:func:`file`
- :f command: :f:func:`command`
- :f commands_list: :f:func:`commands_list`
- :f commands_string: :f:func:`commands_string`
+ :f subroutine close: :f:func:`close`
+ :f subroutine error: :f:func:`error`
+ :f function version: :f:func:`version`
+ :f subroutine file: :f:func:`file`
+ :f subroutine command: :f:func:`command`
+ :f subroutine commands_list: :f:func:`commands_list`
+ :f subroutine commands_string: :f:func:`commands_string`
+ :f function get_natoms: :f:func:`get_natoms`
+ :f function get_thermo: :f:func:`get_thermo`
+ :f subroutine extract_box: :f:func:`extract_box`
+ :f subroutine reset_box: :f:func:`reset_box`
+ :f subroutine memory_usage: :f:func:`memory_usage`
+ :f function extract_setting: :f:func:`extract_setting`
+ :f function extract_global: :f:func:`extract_global`
-.. f:function:: lammps(args[,comm])
+--------
+
+.. f:function:: lammps([args][,comm])
This is the constructor for the Fortran class and will forward
the arguments to a call to either :cpp:func:`lammps_open_fortran`
@@ -198,10 +270,31 @@ of the contents of the ``LIBLAMMPS`` Fortran interface to LAMMPS.
If *comm* is not provided, ``MPI_COMM_WORLD`` is assumed. For
more details please see the documentation of :cpp:func:`lammps_open`.
- :p character(len=*) args(*) [optional]: arguments as list of strings
+ :o character(len=\*) args(\*) [optional]: arguments as list of strings
:o integer comm [optional]: MPI communicator
:r lammps: an instance of the :f:type:`lammps` derived type
+ .. note::
+
+ The ``MPI_F08`` module, which defines Fortran 2008 bindings for MPI,
+ is not directly supported by this interface due to the complexities of
+ supporting both the ``MPI_F08`` and ``MPI`` modules at the same time.
+ However, you should be able to use the ``MPI_VAL`` member of the
+ ``MPI_comm`` derived type to access the integer value of the
+ communicator, such as in
+
+ .. code-block:: Fortran
+
+ PROGRAM testmpi
+ USE LIBLAMMPS
+ USE MPI_F08
+ TYPE(lammps) :: lmp
+ lmp = lammps(MPI_COMM_SELF%MPI_VAL)
+ END PROGRAM testmpi
+
+Procedures Bound to the lammps Derived Type
+===========================================
+
.. f:subroutine:: close([finalize])
This method will close down the LAMMPS instance through calling
@@ -211,6 +304,20 @@ of the contents of the ``LIBLAMMPS`` Fortran interface to LAMMPS.
:o logical finalize [optional]: shut down the MPI environment of the LAMMPS library if true.
+--------
+
+.. f:subroutine:: error(error_type, error_text)
+
+ This method is a wrapper around the :cpp:func:`lammps_error` function and will dispatch
+ an error through the LAMMPS Error class.
+
+ .. versionadded:: TBD
+
+ :p integer error_type: constant to select which Error class function to call
+ :p character(len=\*) error_text: error message
+
+--------
+
.. f:function:: version()
This method returns the numeric LAMMPS version like :cpp:func:`lammps_version`
@@ -224,25 +331,243 @@ of the contents of the ``LIBLAMMPS`` Fortran interface to LAMMPS.
This method will call :cpp:func:`lammps_file` to have LAMMPS read
and process commands from a file.
- :p character(len=*) filename: name of file with LAMMPS commands
+ :p character(len=\*) filename: name of file with LAMMPS commands
+
+--------
.. f:subroutine:: command(cmd)
This method will call :cpp:func:`lammps_command` to have LAMMPS
execute a single command.
- :p character(len=*) cmd: single LAMMPS command
+ :p character(len=\*) cmd: single LAMMPS command
+
+--------
.. f:subroutine:: commands_list(cmds)
This method will call :cpp:func:`lammps_commands_list` to have LAMMPS
execute a list of input lines.
- :p character(len=*) cmd(:): list of LAMMPS input lines
+ :p character(len=\*) cmd(:): list of LAMMPS input lines
+
+--------
.. f:subroutine:: commands_string(str)
This method will call :cpp:func:`lammps_commands_string` to have LAMMPS
execute a block of commands from a string.
- :p character(len=*) str: LAMMPS input in string
+ :p character(len=\*) str: LAMMPS input in string
+
+--------
+
+.. f:function:: get_natoms()
+
+ This function will call :cpp:func:`lammps_get_natoms` and return the number
+ of atoms in the system.
+
+ :r real(c_double): number of atoms
+
+--------
+
+.. f:function:: get_thermo(name)
+
+ This function will call :cpp:func:`lammps_get_thermo` and return the value
+ of the corresponding thermodynamic keyword.
+
+ .. versionadded:: TBD
+
+ :p character(len=\*) name: string with the name of the thermo keyword
+ :r real(c_double): value of the requested thermo property or `0.0_c_double`
+
+--------
+
+.. f:subroutine:: extract_box([boxlo][, boxhi][, xy][, yz][, xz][, pflags][, boxflag])
+
+ This subroutine will call :cpp:func:`lammps_extract_box`. All
+ parameters are optional, though obviously at least one should be
+ present. The parameters *pflags* and *boxflag* are stored in LAMMPS
+ as integers, but should be declared as ``LOGICAL`` variables when
+ calling from Fortran.
+
+ .. versionadded:: TBD
+
+ :o real(c_double) boxlo [dimension(3),optional]: vector in which to store
+ lower-bounds of simulation box
+ :o real(c_double) boxhi [dimension(3),optional]: vector in which to store
+ upper-bounds of simulation box
+ :o real(c_double) xy [optional]: variable in which to store *xy* tilt factor
+ :o real(c_double) yz [optional]: variable in which to store *yz* tilt factor
+ :o real(c_double) xz [optional]: variable in which to store *xz* tilt factor
+ :o logical pflags [dimension(3),optional]: vector in which to store
+ periodicity flags (``.TRUE.`` means periodic in that dimension)
+ :o logical boxflag [optional]: variable in which to store boolean denoting
+ whether the box will change during a simulation
+ (``.TRUE.`` means box will change)
+
+.. note::
+
+ Note that a frequent use case of this function is to extract only one or
+ more of the options rather than all seven. For example, assuming "lmp"
+ represents a properly-initialized LAMMPS instance, the following code will
+ extract the periodic box settings into the variable "periodic":
+
+ .. code-block:: Fortran
+
+ ! code to start up
+ logical :: periodic(3)
+ ! code to initialize LAMMPS / run things / etc.
+ call lmp%extract_box(pflags = periodic)
+
+--------
+
+.. f:subroutine:: reset_box(boxlo, boxhi, xy, yz, xz)
+
+ This subroutine will call :cpp:func:`lammps_reset_box`. All parameters
+ are required.
+
+ .. versionadded:: TBD
+
+ :p real(c_double) boxlo [dimension(3)]: vector of three doubles containing
+ the lower box boundary
+ :p real(c_double) boxhi [dimension(3)]: vector of three doubles containing
+ the upper box boundary
+ :p real(c_double) xy: *x--y* tilt factor
+ :p real(c_double) yz: *y--z* tilt factor
+ :p real(c_double) xz: *x--z* tilt factor
+
+--------
+
+.. f:subroutine:: memory_usage(meminfo)
+
+ This subroutine will call :cpp:func:`lammps_memory_usage` and store the
+ result in the three-element array *meminfo*.
+
+ .. versionadded:: TBD
+
+ :p real(c_double) meminfo [dimension(3)]: vector of three doubles in which
+ to store memory usage data
+
+--------
+
+.. f:function:: get_mpi_comm()
+
+ This function returns a Fortran representation of the LAMMPS "world"
+ communicator.
+
+ .. versionadded:: TBD
+
+ :r integer: Fortran integer equivalent to the MPI communicator LAMMPS is
+ using
+
+ .. note::
+
+ The C library interface currently returns type ``int`` instead of
+ type ``MPI_Fint``, which is the C type corresponding to Fortran
+ ``INTEGER`` types of the default kind. On most compilers, these
+ are the same anyway, but this interface exchanges values this way
+ to avoid warning messages.
+
+ .. note::
+
+ The `MPI_F08` module, which defines Fortran 2008 bindings for MPI,
+ is not directly supported by this function. However, you should be
+ able to convert between the two using the `MPI_VAL` member of the
+ communicator. For example,
+
+ .. code-block:: fortran
+
+ USE MPI_F08
+ USE LIBLAMMPS
+ TYPE (LAMMPS) :: lmp
+ TYPE (MPI_Comm) :: comm
+ ! ... [commands to set up LAMMPS/etc.]
+ comm%MPI_VAL = lmp%get_mpi_comm()
+
+ should assign an `MPI_F08` communicator properly.
+
+--------
+
+.. f:function:: extract_setting(keyword)
+
+ Query LAMMPS about global settings. See the documentation for the
+ :cpp:func:`lammps_extract_setting` function from the C library.
+
+ .. versionadded:: TBD
+
+ :p character(len=\*) keyword: string containing the name of the thermo keyword
+ :r integer(c_int): value of the queried setting or :math:`-1` if unknown
+
+--------
+
+.. f:function:: extract_global(name)
+
+ This function calls :cpp:func:`lammps_extract_global` and returns
+ either a string or a pointer to internal global LAMMPS data,
+ depending on the data requested through *name*.
+
+ .. versionadded:: TBD
+
+ Note that this function actually does not return a value, but rather
+ associates the pointer on the left side of the assignment to point to
+ internal LAMMPS data (with the exception of string data, which are
+ copied and returned as ordinary Fortran strings). Pointers must be of
+ the correct data type to point to said data (typically
+ ``INTEGER(c_int)``, ``INTEGER(c_int64_t)``, or ``REAL(c_double)``)
+ and have compatible kind and rank. The pointer being associated with
+ LAMMPS data is type-, kind-, and rank-checked at run-time via an
+ overloaded assignment operator. The pointers returned by this
+ function are generally persistent; therefore it is not necessary to
+ call the function again, unless a :doc:`clear` command has been
+ issued, which wipes out and recreates the contents of the
+ :cpp:class:`LAMMPS ` class.
+
+ For example,
+
+ .. code-block:: fortran
+
+ PROGRAM demo
+ USE, INTRINSIC :: ISO_C_BINDING, ONLY : c_int64_t
+ USE LIBLAMMPS
+ TYPE(lammps) :: lmp
+ INTEGER(c_int), POINTER :: nlocal
+ INTEGER(c_int64_t), POINTER :: ntimestep
+ CHARACTER(LEN=10) :: units
+ REAL(c_double), POINTER :: dt
+ lmp = lammps()
+ ! other commands
+ nlocal = lmp%extract_global('nlocal')
+ ntimestep = lmp%extract_global('ntimestep')
+ dt = lmp%extract_global('dt')
+ units = lmp%extract_global('units')
+ ! more commands
+ lmp.close(.TRUE.)
+ END PROGRAM demo
+
+ would extract the number of atoms on this processor, the current time step,
+ the size of the current time step, and the units being used into the
+ variables *nlocal*, *ntimestep*, *dt*, and *units*, respectively.
+
+ .. note::
+
+ if this function returns a string, the string must have
+ length greater than or equal to the length of the string (not including the
+ terminal NULL character) that LAMMPS returns. If the variable's length is
+ too short, the string will be truncated. As usual in Fortran, strings
+ are padded with spaces at the end.
+
+ :p character(len=\*) name: string with the name of the extracted property
+ :r polymorphic: pointer to LAMMPS data. The left-hand side of the assignment
+ should be either a string (if expecting string data) or a C-compatible
+ pointer (e.g., ``INTEGER (c_int), POINTER :: nlocal``) to the extracted
+ property. If expecting vector data, the pointer should have dimension ":".
+
+.. warning::
+
+ Modifying the data in the location pointed to by the returned pointer
+ may lead to inconsistent internal data and thus may cause failures or
+ crashes or bogus simulations. In general it is thus usually better
+ to use a LAMMPS input command that sets or changes these parameters.
+ Those will take care of all side effects and necessary updates of
+ settings derived from such settings.
diff --git a/doc/src/Howto.rst b/doc/src/Howto.rst
index b4f14bccfa..715f13f09b 100644
--- a/doc/src/Howto.rst
+++ b/doc/src/Howto.rst
@@ -34,6 +34,7 @@ Settings howto
:maxdepth: 1
Howto_2d
+ Howto_type_labels
Howto_triclinic
Howto_thermostat
Howto_barostat
diff --git a/doc/src/Howto_amoeba.rst b/doc/src/Howto_amoeba.rst
index c6df8a9b5c..6b84fc9f00 100644
--- a/doc/src/Howto_amoeba.rst
+++ b/doc/src/Howto_amoeba.rst
@@ -281,7 +281,7 @@ Here is more information about the extended XYZ format defined and
used by Tinker, and links to programs that convert standard PDB files
to the extended XYZ format:
-* `http://openbabel.org/docs/current/FileFormats/Tinker_XYZ_format.html `_
+* `https://openbabel.org/docs/current/FileFormats/Tinker_XYZ_format.html `_
* `https://github.com/emleddin/pdbxyz-xyzpdb `_
* `https://github.com/TinkerTools/tinker/blob/release/source/pdbxyz.f `_
diff --git a/doc/src/Howto_bioFF.rst b/doc/src/Howto_bioFF.rst
index 172ba3da3a..8899f7520c 100644
--- a/doc/src/Howto_bioFF.rst
+++ b/doc/src/Howto_bioFF.rst
@@ -3,24 +3,20 @@ CHARMM, AMBER, COMPASS, and DREIDING force fields
A force field has 2 parts: the formulas that define it and the
coefficients used for a particular system. Here we only discuss
-formulas implemented in LAMMPS that correspond to formulas commonly
-used in the CHARMM, AMBER, COMPASS, and DREIDING force fields. Setting
+formulas implemented in LAMMPS that correspond to formulas commonly used
+in the CHARMM, AMBER, COMPASS, and DREIDING force fields. Setting
coefficients is done either from special sections in an input data file
via the :doc:`read_data ` command or in the input script with
-commands like :doc:`pair_coeff ` or
-:doc:`bond_coeff ` and so on. See the :doc:`Tools ` doc
-page for additional tools that can use CHARMM, AMBER, or Materials
-Studio generated files to assign force field coefficients and convert
-their output into LAMMPS input.
+commands like :doc:`pair_coeff ` or :doc:`bond_coeff
+` and so on. See the :doc:`Tools ` doc page for
+additional tools that can use CHARMM, AMBER, or Materials Studio
+generated files to assign force field coefficients and convert their
+output into LAMMPS input.
-See :ref:`(MacKerell) ` for a description of the CHARMM force
-field. See :ref:`(Cornell) ` for a description of the AMBER
-force field. See :ref:`(Sun) ` for a description of the COMPASS
-force field.
-
-.. _charmm: http://www.scripps.edu/brooks
-
-.. _amber: http://amber.scripps.edu
+See :ref:`(MacKerell) ` for a description of the CHARMM
+force field. See :ref:`(Cornell) ` for a description of
+the AMBER force field. See :ref:`(Sun) ` for a description
+of the COMPASS force field.
The interaction styles listed below compute force field formulas that
are consistent with common options in CHARMM or AMBER. See each
@@ -41,9 +37,10 @@ command's documentation for the formula it computes.
.. note::
- For CHARMM, newer *charmmfsw* or *charmmfsh* styles were released
- in March 2017. We recommend they be used instead of the older *charmm*
- styles. See discussion of the differences on the :doc:`pair charmm ` and :doc:`dihedral charmm ` doc
+ For CHARMM, newer *charmmfsw* or *charmmfsh* styles were released in
+ March 2017. We recommend they be used instead of the older *charmm*
+ styles. See discussion of the differences on the :doc:`pair charmm
+ ` and :doc:`dihedral charmm ` doc
pages.
COMPASS is a general force field for atomistic simulation of common
diff --git a/doc/src/Howto_bpm.rst b/doc/src/Howto_bpm.rst
index 2f015162e0..46e7e70131 100644
--- a/doc/src/Howto_bpm.rst
+++ b/doc/src/Howto_bpm.rst
@@ -33,46 +33,6 @@ reference state of a bond. Bonds that are created midway into a run,
such as those created by pouring grains using :doc:`fix pour
`, are initialized on that timestep.
-As bonds can be broken between neighbor list builds, the
-:doc:`special_bonds ` command works differently for BPM
-bond styles. There are two possible settings which determine how pair
-interactions work between bonded particles. First, one can turn off
-all pair interactions between bonded particles. Unlike :doc:`bond
-quartic `, this is not done by subtracting pair forces
-during the bond computation but rather by dynamically updating the
-special bond list. This is the default behavior of BPM bond styles and
-is done by updating the 1-2 special bond list as bonds break. To do
-this, LAMMPS requires :doc:`newton ` bond off such that all
-processors containing an atom know when a bond breaks. Additionally,
-one must do either (A) or (B).
-
-A) Use the following special bond settings
-
- .. code-block:: LAMMPS
-
- special_bonds lj 0 1 1 coul 1 1 1
-
- These settings accomplish two goals. First, they turn off 1-3 and 1-4
- special bond lists, which are not currently supported for BPMs. As
- BPMs often have dense bond networks, generating 1-3 and 1-4 special
- bond lists is expensive. By setting the lj weight for 1-2 bonds to
- zero, this turns off pairwise interactions. Even though there are no
- charges in BPM models, setting a nonzero coul weight for 1-2 bonds
- ensures all bonded neighbors are still included in the neighbor list
- in case bonds break between neighbor list builds.
-
-B) Alternatively, one can simply overlay pair interactions such that all
- bonded particles also feel pair interactions. This can be
- accomplished by using the *overlay/pair* keyword present in all bpm
- bond styles and by using the following special bond settings
-
- .. code-block:: LAMMPS
-
- special_bonds lj/coul 1 1 1
-
-See the :doc:`Howto ` page on broken bonds for
-more information.
-
----------
Currently there are two types of bonds included in the BPM
@@ -91,12 +51,6 @@ This also requires a unique integrator :doc:`fix nve/bpm/sphere
` which numerically integrates orientation similar
to :doc:`fix nve/asphere `.
-To monitor the fracture of bonds in the system, all BPM bond styles
-have the ability to record instances of bond breakage to output using
-the :doc:`dump local ` command. Additionally, one can use
-:doc:`compute nbond/atom ` to tally the current
-number of bonds per atom.
-
In addition to bond styles, a new pair style :doc:`pair bpm/spring
` was added to accompany the bpm/spring bond
style. This pair style is simply a hookean repulsion with similar
@@ -104,6 +58,73 @@ velocity damping as its sister bond style.
----------
+Bond data can be output using a combination of standard LAMMPS commands.
+A list of IDs for bonded atoms can be generated using the
+:doc:`compute property/local ` command.
+Various properties of bonds can be computed using the
+:doc:`compute bond/local ` command. This
+command allows one to access data saved to the bond's history
+such as the reference length of the bond. More information on
+bond history data can be found on the documentation pages for the specific
+BPM bond styles. Finally, this data can be output using a :doc:`dump local `
+command. As one may output many columns from the same compute, the
+:doc:`dump modify ` *colname* option may be used to provide
+more helpful column names. An example of this procedure is found in
+/examples/bpm/pour/. External software, such as OVITO, can read these dump
+files to render bond data.
+
+----------
+
+As bonds can be broken between neighbor list builds, the
+:doc:`special_bonds ` command works differently for BPM
+bond styles. There are two possible settings which determine how pair
+interactions work between bonded particles. First, one can overlay
+pair forces with bond forces such that all bonded particles also
+feel pair interactions. This can be accomplished by using the *overlay/pair*
+keyword present in all bpm bond styles and by using the following special
+bond settings
+
+ .. code-block:: LAMMPS
+
+ special_bonds lj/coul 1 1 1
+
+Alternatively, one can turn off all pair interactions between bonded
+particles. Unlike :doc:`bond quartic `, this is not done
+by subtracting pair forces during the bond computation but rather by
+dynamically updating the special bond list. This is the default behavior
+of BPM bond styles and is done by updating the 1-2 special bond list as
+bonds break. To do this, LAMMPS requires :doc:`newton ` bond off
+such that all processors containing an atom know when a bond breaks.
+Additionally, one must use the following special bond settings
+
+ .. code-block:: LAMMPS
+
+ special_bonds lj 0 1 1 coul 1 1 1
+
+These settings accomplish two goals. First, they turn off 1-3 and 1-4
+special bond lists, which are not currently supported for BPMs. As
+BPMs often have dense bond networks, generating 1-3 and 1-4 special
+bond lists is expensive. By setting the lj weight for 1-2 bonds to
+zero, this turns off pairwise interactions. Even though there are no
+charges in BPM models, setting a nonzero coul weight for 1-2 bonds
+ensures all bonded neighbors are still included in the neighbor list
+in case bonds break between neighbor list builds.
+
+To monitor the fracture of bonds in the system, all BPM bond styles
+have the ability to record instances of bond breakage to output using
+the :doc:`dump local ` command. Since one may frequently output
+a list of broken bonds and the time they broke, the
+:doc:`dump modify ` option *header no* may be useful to
+avoid repeatedly printing the header of the dump file. An example of
+this procedure is found in /examples/bpm/impact/. Additionally,
+one can use :doc:`compute nbond/atom ` to tally the
+current number of bonds per atom.
+
+See the :doc:`Howto ` page on broken bonds for
+more information.
+
+----------
+
While LAMMPS has many utilities to create and delete bonds, *only*
the following are currently compatible with BPM bond styles:
diff --git a/doc/src/Howto_github.rst b/doc/src/Howto_github.rst
index 315bacac69..9209477986 100644
--- a/doc/src/Howto_github.rst
+++ b/doc/src/Howto_github.rst
@@ -10,7 +10,7 @@ changes or additions you have made to LAMMPS into the official LAMMPS
distribution. It uses the process of updating this very tutorial as an
example to describe the individual steps and options. You need to be
familiar with git and you may want to have a look at the `git book
-` reference for more details on both
the SPC and SPC/E models.
-Wikipedia also has a nice article on `water models `_.
+Wikipedia also has a nice article on `water models `_.
----------
diff --git a/doc/src/Howto_spins.rst b/doc/src/Howto_spins.rst
index 87e30a5f6f..8ca220f596 100644
--- a/doc/src/Howto_spins.rst
+++ b/doc/src/Howto_spins.rst
@@ -30,9 +30,11 @@ can be coupled to another Langevin thermostat applied to the atoms
using :doc:`fix langevin ` in order to simulate
thermostatted spin-lattice systems.
-The magnetic Gilbert damping can also be applied using :doc:`fix langevin/spin `. It allows to either dissipate
-the thermal energy of the Langevin thermostat, or to perform a
-relaxation of the magnetic configuration toward an equilibrium state.
+The magnetic damping can also be applied
+using :doc:`fix langevin/spin `.
+It allows to either dissipate the thermal energy of the Langevin
+thermostat, or to perform a relaxation of the magnetic configuration
+toward an equilibrium state.
The command :doc:`fix setforce/spin ` allows to set the
components of the magnetic precession vectors (while erasing and
@@ -52,9 +54,11 @@ All the computed magnetic properties can be output by two main
commands. The first one is :doc:`compute spin `, that
enables to evaluate magnetic averaged quantities, such as the total
magnetization of the system along x, y, or z, the spin temperature, or
-the magnetic energy. The second command is :doc:`compute property/atom `. It enables to output all the
-per atom magnetic quantities. Typically, the orientation of a given
-magnetic spin, or the magnetic force acting on this spin.
+the magnetic energy. The second command
+is :doc:`compute property/atom `.
+It enables to output all the per atom magnetic quantities. Typically,
+the orientation of a given magnetic spin, or the magnetic force
+acting on this spin.
----------
diff --git a/doc/src/Howto_tip3p.rst b/doc/src/Howto_tip3p.rst
index 7f7ddbdf2a..5571b3291a 100644
--- a/doc/src/Howto_tip3p.rst
+++ b/doc/src/Howto_tip3p.rst
@@ -49,7 +49,7 @@ details:
| :math:`\theta` of HOH angle = 104.52\ :math:`^{\circ}`
|
-Wikipedia also has a nice article on `water models `_.
+Wikipedia also has a nice article on `water models `_.
----------
diff --git a/doc/src/Howto_tip4p.rst b/doc/src/Howto_tip4p.rst
index 9856b8fbe7..4e0a63adc6 100644
--- a/doc/src/Howto_tip4p.rst
+++ b/doc/src/Howto_tip4p.rst
@@ -97,7 +97,7 @@ This leads to slightly larger cost for the long-range calculation, so
you can test the trade-off for your model. The OM distance and the LJ
and Coulombic cutoffs are set in the :doc:`pair_style lj/cut/tip4p/long ` command.
-Wikipedia also has a nice article on `water models `_.
+Wikipedia also has a nice article on `water models `_.
----------
diff --git a/doc/src/Howto_type_labels.rst b/doc/src/Howto_type_labels.rst
new file mode 100644
index 0000000000..8f03f45ef9
--- /dev/null
+++ b/doc/src/Howto_type_labels.rst
@@ -0,0 +1,126 @@
+Type labels
+===========
+
+.. versionadded:: 15Sep2022
+
+Each atom in LAMMPS has an associated numeric atom type. Similarly,
+each bond, angle, dihedral, and improper is assigned a bond type,
+angle type, and so on. The primary use of these types is to map
+potential (force field) parameters to the interactions of the atom,
+bond, angle, dihedral, and improper.
+
+By default, type values are entered as integers from 1 to Ntypes
+wherever they appear in LAMMPS input or output files. The total number
+Ntypes for each interaction is "locked in" when the simulation box
+is created.
+
+A recent addition to LAMMPS is the option to use strings - referred
+to as type labels - as an alternative. Using type labels instead of
+numeric types can be advantageous in various scenarios. For example,
+type labels can make inputs more readable and generic (i.e. usable through
+the :doc:`include command ` for different systems with different
+numerical values assigned to types. This generality also applies to
+other inputs like data files read by :doc:`read_data ` or
+molecule template files read by the :doc:`molecule `
+command. See below for a list of other commands that can use
+type labels in different ways.
+
+LAMMPS will *internally* continue to use numeric types, which means
+that many previous restrictions still apply. For example, the total
+number of types is locked in when creating the simulation box, and
+potential parameters for each type must be provided even if not used
+by any interactions.
+
+A collection of type labels for all type-kinds (atom types, bond types,
+etc.) is stored as a "label map" which is simply a list of numeric types
+and their associated type labels. Within a type-kind, each type label
+must be unique. It can be assigned to only one numeric type. To read
+and write type labels to data files for a given type-kind, *all*
+associated numeric types need have a type label assigned. Partial
+maps can be saved with the :doc:`labelmap write ` command
+and read back with the :doc:`include ` command.
+
+Valid type labels can contain most ASCII characters, but cannot start
+with a number, a '#', or a '*'. Also, labels must not contain whitespace
+characters. When using the :doc:`labelmap command ` in the
+LAMMPS input, if certain characters appear in the type label, such as
+the single (') or double (") quote or the '#' character, the label
+must be put in either double, single, or triple (""") quotes. Triple
+quotes allow for the most generic type label strings, but they require
+to have a leading and trailing blank space. When defining type labels
+the blanks will be ignored. Example:
+
+.. code-block:: LAMMPS
+
+ labelmap angle 1 """ C1'-C2"-C3# """
+
+This command will map the string ```C1'-C2"-C3#``` to the angle type 1.
+
+There are two ways to define label maps. One is via the :doc:`labelmap
+` command. The other is via the :doc:`read_data `
+command. A data file can have sections such as *Atom Type Labels*, *Bond
+Type Labels*, etc., which assign type labels to numeric types. The
+label map can be written out to data files by the :doc:`write_data
+` command. This map is also written to and read from
+restart files, by the :doc:`write_restart ` and
+:doc:`read_restart ` commands.
+
+----------
+
+Use of type labels in LAMMPS input or output
+""""""""""""""""""""""""""""""""""""""""""""
+
+Many LAMMPS input script commands that take a numeric type as an
+argument can use the associated type label instead. If a type label
+is not defined for a particular numeric type, only its numeric type
+can be used.
+
+This example assigns labels to the atom types, and then uses the type
+labels to redefine the pair coefficients.
+
+.. code-block:: LAMMPS
+
+ pair_coeff 1 2 1.0 1.0 # numeric types
+ labelmap atom 1 C 2 H
+ pair_coeff C H 1.0 1.0 # type labels
+
+Adding support for type labels to various commands is an ongoing
+project. If an input script command (or a section in a file read by a
+command) allows substituting a type label for a numeric type argument,
+it will be explicitly mentioned in that command's documentation page.
+
+As a temporary measure, input script commands can take advantage of
+variables and how they can be expanded during processing of the input.
+The variables can use functions that will translate type label strings
+to their respective number as defined in the current label map. See the
+:doc:`variable ` command for details.
+
+For example, here is how the pair_coeff command could be used with
+type labels if it did not yet support them, either with an explicit
+variable command or an implicit variable used in the pair_coeff
+command.
+
+.. code-block:: LAMMPS
+
+ labelmap atom 1 C 2 H
+ variable atom1 equal label2type(atom,C)
+ variable atom2 equal label2type(atom,H)
+ pair_coeff ${atom1} ${atom2} 1.0 1.0
+
+.. code-block:: LAMMPS
+
+ labelmap atom 1 C 2 H
+ pair_coeff $(label2type(atom,C)) $(label2type(atom,H)) 80.0 1.2
+
+----------
+
+Commands that can use label types
+"""""""""""""""""""""""""""""""""
+
+Any workflow that involves reading multiple data files, molecule
+templates or a combination of the two can be streamlined by using type
+labels instead of numeric types, because types are automatically synced
+between the files. The creation of simulation-ready reaction templates
+for :doc:`fix bond/react ` is much simpler when using
+type labels, and results in templates that can be used without
+modification in multiple simulations or different systems.
diff --git a/doc/src/Howto_viz.rst b/doc/src/Howto_viz.rst
index 7c74aab8bf..28ecbfb838 100644
--- a/doc/src/Howto_viz.rst
+++ b/doc/src/Howto_viz.rst
@@ -17,9 +17,10 @@ formats. See the :doc:`Tools ` page for details.
A Python-based toolkit distributed by our group can read native LAMMPS
dump files, including custom dump files with additional columns of
-user-specified atom information, and convert them to various formats
-or pipe them into visualization software directly. See the `Pizza.py WWW site `_ for details. Specifically, Pizza.py can convert
-LAMMPS dump files into PDB, XYZ, `EnSight `_, and VTK formats.
+user-specified atom information, and convert them to various formats or
+pipe them into visualization software directly. See the `Pizza.py WWW
+site `_ for details. Specifically, Pizza.py can convert LAMMPS
+dump files into PDB, XYZ, `EnSight `_, and VTK formats.
Pizza.py can pipe LAMMPS dump files directly into the Raster3d and
RasMol visualization programs. Pizza.py has tools that do interactive
3d OpenGL visualization and one that creates SVG images of dump file
diff --git a/doc/src/Install_conda.rst b/doc/src/Install_conda.rst
index efb7b6146a..34b45fcf8b 100644
--- a/doc/src/Install_conda.rst
+++ b/doc/src/Install_conda.rst
@@ -5,7 +5,7 @@ Binaries are available for MacOS or Linux via `Conda `_.
First, one must setup the Conda package manager on your system. Follow the
instructions to install `Miniconda `_, then create a conda
-environment (named `my-lammps-env` or whatever you prefer) for your lammps
+environment (named `my-lammps-env` or whatever you prefer) for your LAMMPS
install:
.. code-block:: bash
@@ -13,7 +13,7 @@ install:
% conda config --add channels conda-forge
% conda create -n my-lammps-env
-Then, you can install lammps on your system with the following command:
+Then, you can install LAMMPS on your system with the following command:
.. code-block:: bash
diff --git a/doc/src/Install_windows.rst b/doc/src/Install_windows.rst
index 108c03c249..fc167d7e68 100644
--- a/doc/src/Install_windows.rst
+++ b/doc/src/Install_windows.rst
@@ -6,7 +6,7 @@ Windows system can be downloaded from this site:
.. parsed-literal::
- `http://packages.lammps.org/windows.html `_
+ `https://packages.lammps.org/windows.html `_
Note that each installer package has a date in its name, which
corresponds to the LAMMPS version of the same date. Installers for
diff --git a/doc/src/Intro_authors.rst b/doc/src/Intro_authors.rst
index a0902ccda1..b76e2486de 100644
--- a/doc/src/Intro_authors.rst
+++ b/doc/src/Intro_authors.rst
@@ -4,13 +4,13 @@ Authors of LAMMPS
The primary LAMMPS developers are at Sandia National Labs and Temple
University:
-* `Steve Plimpton `_, sjplimp at sandia.gov
+* `Steve Plimpton `_, sjplimp at gmail.com
* Aidan Thompson, athomps at sandia.gov
* Stan Moore, stamoor at sandia.gov
* Axel Kohlmeyer, akohlmey at gmail.com
* Richard Berger, richard.berger at outlook.com
-.. _sjp: http://www.cs.sandia.gov/~sjplimp
+.. _sjp: https://sjplimp.github.io
.. _lws: https://www.lammps.org
Past developers include Paul Crozier and Mark Stevens, both at Sandia,
diff --git a/doc/src/Intro_citing.rst b/doc/src/Intro_citing.rst
index aaf62028ae..56955cae3a 100644
--- a/doc/src/Intro_citing.rst
+++ b/doc/src/Intro_citing.rst
@@ -27,7 +27,7 @@ namely https://www.lammps.org.
The original publication describing the parallel algorithms used in the
initial versions of LAMMPS is:
- `S. Plimpton, Fast Parallel Algorithms for Short-Range Molecular Dynamics, J Comp Phys, 117, 1-19 (1995). `_
+ `S. Plimpton, Fast Parallel Algorithms for Short-Range Molecular Dynamics, J Comp Phys, 117, 1-19 (1995). `_
DOI for the LAMMPS source code
diff --git a/doc/src/Intro_features.rst b/doc/src/Intro_features.rst
index 2b0409b007..9344710a16 100644
--- a/doc/src/Intro_features.rst
+++ b/doc/src/Intro_features.rst
@@ -95,7 +95,7 @@ commands)
* metal-organic framework potentials (QuickFF, MO-FF)
* implicit solvent potentials: hydrodynamic lubrication, Debye
* force-field compatibility with common CHARMM, AMBER, DREIDING, OPLS, GROMACS, COMPASS options
-* access to the `OpenKIM Repository `_ of potentials via :doc:`kim command `
+* access to the `OpenKIM Repository `_ of potentials via the :doc:`kim command `
* hybrid potentials: multiple pair, bond, angle, dihedral, improper potentials can be used in one simulation
* overlaid potentials: superposition of multiple pair potentials (including many-body) with optional scale factor
@@ -205,7 +205,7 @@ Pre- and post-processing
.. _pizza: https://lammps.github.io/pizza
-.. _python: http://www.python.org
+.. _python: https://www.python.org
.. _special:
diff --git a/doc/src/Intro_nonfeatures.rst b/doc/src/Intro_nonfeatures.rst
index d9a977196f..b1d68c8594 100644
--- a/doc/src/Intro_nonfeatures.rst
+++ b/doc/src/Intro_nonfeatures.rst
@@ -33,7 +33,7 @@ Here are suggestions on how to perform these tasks:
linear bead-spring polymer chains. The moltemplate program is a true
molecular builder that will generate complex molecular models. See
the :doc:`Tools ` page for details on tools packaged with
- LAMMPS. The `Pre/post processing page `_ of the LAMMPS website
+ LAMMPS. The `Pre/post processing page `_ of the LAMMPS website
describes a variety of third party tools for this task. Furthermore,
some LAMMPS internal commands allow to reconstruct, or selectively add
topology information, as well as provide the option to insert molecule
@@ -80,5 +80,5 @@ Here are suggestions on how to perform these tasks:
`Pizza.py `_ which can do certain kinds of
setup, analysis, plotting, and visualization (via OpenGL) for LAMMPS
simulations. It thus provides some functionality for several of the
- above bullets. Pizza.py is written in `Python `_
- and is available for download from `this page `_.
+ above bullets. Pizza.py is written in `Python `_
+ and is available for download from `this page `_.
diff --git a/doc/src/Intro_opensource.rst b/doc/src/Intro_opensource.rst
index a1baaf5185..fba0a78189 100644
--- a/doc/src/Intro_opensource.rst
+++ b/doc/src/Intro_opensource.rst
@@ -23,9 +23,9 @@ applies to LAMMPS is in the LICENSE file included in the LAMMPS distribution.
.. _lgpl: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html
-.. _gnuorg: http://www.gnu.org
+.. _gnuorg: https://www.gnu.org
-.. _opensource: http://www.opensource.org
+.. _opensource: https://www.opensource.org
Here is a more specific summary of what the GPL means for LAMMPS users:
diff --git a/doc/src/Library_create.rst b/doc/src/Library_create.rst
index 8043819891..8ccc2e80ce 100644
--- a/doc/src/Library_create.rst
+++ b/doc/src/Library_create.rst
@@ -11,6 +11,7 @@ This section documents the following functions:
- :cpp:func:`lammps_mpi_finalize`
- :cpp:func:`lammps_kokkos_finalize`
- :cpp:func:`lammps_python_finalize`
+- :cpp:func:`lammps_error`
--------------------
@@ -115,3 +116,8 @@ calling program.
.. doxygenfunction:: lammps_python_finalize
:project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_error
+ :project: progguide
diff --git a/doc/src/Library_properties.rst b/doc/src/Library_properties.rst
index e023c78185..a5c9c79c64 100644
--- a/doc/src/Library_properties.rst
+++ b/doc/src/Library_properties.rst
@@ -15,21 +15,21 @@ This section documents the following functions:
--------------------
-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
+The library interface allows the extraction of different kinds of
+information about the active simulation instance and also - in some
+cases - to apply 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
diff --git a/doc/src/Library_utility.rst b/doc/src/Library_utility.rst
index da64e3b8f0..9d16daae0b 100644
--- a/doc/src/Library_utility.rst
+++ b/doc/src/Library_utility.rst
@@ -19,6 +19,7 @@ functions. They do not directly call the LAMMPS library.
- :cpp:func:`lammps_force_timeout`
- :cpp:func:`lammps_has_error`
- :cpp:func:`lammps_get_last_error_message`
+- :cpp:func:`lammps_python_api_version`
The :cpp:func:`lammps_free` function is a clean-up function to free
memory that the library had allocated previously via other function
@@ -100,3 +101,9 @@ where such memory buffers were allocated that require the use of
.. doxygenfunction:: lammps_get_last_error_message
:project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_python_api_version
+ :project: progguide
+
diff --git a/doc/src/Packages_details.rst b/doc/src/Packages_details.rst
index f2291b231e..85857a4e1d 100644
--- a/doc/src/Packages_details.rst
+++ b/doc/src/Packages_details.rst
@@ -134,6 +134,8 @@ commands to write and read data using the ADIOS library.
**Authors:** Norbert Podhorszki (ORNL) from the ADIOS developer team.
+.. versionadded:: 28Feb2019
+
**Install:**
This package has :ref:`specific installation instructions ` on the :doc:`Build extras ` page.
@@ -276,7 +278,7 @@ the barostat as outlined in:
N. J. H. Dunn and W. G. Noid, "Bottom-up coarse-grained models that
accurately describe the structure, pressure, and compressibility of
-molecular liquids," J. Chem. Phys. 143, 243148 (2015).
+molecular liquids", J. Chem. Phys. 143, 243148 (2015).
**Authors:** Nicholas J. H. Dunn and Michael R. DeLyser (The
Pennsylvania State University)
@@ -364,6 +366,8 @@ and also support self-propelled particles.
**Authors:** Sam Cameron (University of Bristol),
Stefan Paquay (while at Brandeis University) (initial version of fix propel/self)
+.. versionadded:: 14May2021
+
Example inputs are in the examples/PACKAGES/brownian folder.
----------
@@ -592,6 +596,8 @@ To use this package, also the :ref:`KSPACE ` and
**Author:** Trung Nguyen and Monica Olvera de la Cruz (Northwestern U)
+.. versionadded:: 2Jul2021
+
**Supporting info:**
* src/DIELECTRIC: filenames -> commands
@@ -932,6 +938,10 @@ EXTRA-MOLECULE package
Additional bond, angle, dihedral, and improper styles that are less commonly used.
+**Install:**
+
+To use this package, also the :ref:`MOLECULE ` package needs to be installed.
+
**Supporting info:**
* src/EXTRA-MOLECULE: filenames -> commands
@@ -1067,7 +1077,7 @@ H5MD is a format for molecular simulations, built on top of HDF5.
This package implements a :doc:`dump h5md ` command to output
LAMMPS snapshots in this format.
-.. _HDF5: http://www.hdfgroup.org/HDF5
+.. _HDF5: https://www.hdfgroup.org/solutions/hdf5
To use this package you must have the HDF5 library available on your
system.
@@ -1508,6 +1518,8 @@ workflows via the `MolSSI Driver Interface
**Author:** Taylor Barnes - MolSSI, taylor.a.barnes at gmail.com
+.. versionadded:: 14May2021
+
**Install:**
This package has :ref:`specific installation instructions ` on
@@ -1592,6 +1604,8 @@ of Alabama), Leonid V. Zhigilei (University of Virginia)
**Author of the *mesocnt* styles:**
Philipp Kloza (U Cambridge)
+.. versionadded:: 15Jun2020
+
**Supporting info:**
* src/MESONT: filenames -> commands
@@ -1684,6 +1698,8 @@ compiled on your system.
**Author:** Andreas Singraber
+.. versionadded:: 27May2021
+
**Install:**
This package has :ref:`specific installation instructions ` on the
@@ -1718,6 +1734,10 @@ must be installed.
**Author:** Aidan Thompson (Sandia), Nicholas Lubbers (LANL).
+.. versionadded:: 30Jun2020
+
+ .. versionadded:: 30Jun2020
+
**Supporting info:**
* src/ML-IAP: filenames -> commands
@@ -1762,6 +1782,8 @@ Aidan Thompson^3, Gabor Csanyi^2, Christoph Ortner^4, Ralf Drautz^1.
^4: University of British Columbia, Vancouver, BC, Canada
+.. versionadded:: 14May2021
+
**Install:**
This package has :ref:`specific installation instructions ` on the
@@ -1825,6 +1847,8 @@ of a neural network.
This package was written by Christopher Barrett
with contributions by Doyl Dickel, Mississippi State University.
+.. versionadded:: 27May2021
+
**Supporting info:**
* src/ML-RANN: filenames -> commands
@@ -1950,7 +1974,7 @@ support for new file formats can be added to LAMMPS (or VMD or other
programs that use them) without having to re-compile the application
itself. More information about the VMD molfile plugins can be found
at
-`http://www.ks.uiuc.edu/Research/vmd/plugins/molfile `_.
+`https://www.ks.uiuc.edu/Research/vmd/plugins/molfile `_.
**Author:** Axel Kohlmeyer (Temple U).
@@ -2041,7 +2065,7 @@ NETCDF package
Dump styles for writing NetCDF formatted dump files. NetCDF is a
portable, binary, self-describing file format developed on top of
HDF5. The file contents follow the AMBER NetCDF trajectory conventions
-(http://ambermd.org/netcdf/nctraj.xhtml), but include extensions.
+(https://ambermd.org/netcdf/nctraj.xhtml), but include extensions.
To use this package you must have the NetCDF library available on your
system.
@@ -2052,7 +2076,7 @@ tools:
* `Ovito `_ (Ovito supports the AMBER convention and the extensions mentioned above)
* `VMD `_
-.. _ovito: http://www.ovito.org
+.. _ovito: https://www.ovito.org
.. _vmd-home: https://www.ks.uiuc.edu/Research/vmd/
@@ -2260,6 +2284,8 @@ try to load the contained plugins automatically at start-up.
**Authors:** Axel Kohlmeyer (Temple U)
+.. versionadded:: 8Apr2021
+
**Supporting info:**
* src/PLUGIN: filenames -> commands
@@ -2413,7 +2439,7 @@ A :doc:`fix qmmm ` command which allows LAMMPS to be used as
the MM code in a QM/MM simulation. This is currently only available
in combination with the `Quantum ESPRESSO `_ package.
-.. _espresso: http://www.quantum-espresso.org
+.. _espresso: https://www.quantum-espresso.org
To use this package you must have Quantum ESPRESSO (QE) available on
your system and include its coupling library in the compilation and
@@ -2825,7 +2851,7 @@ collection of atoms by wrapping the `Voro++ library `_. This
can be used to calculate the local volume or each atoms or its near
neighbors.
-.. _voro-home: http://math.lbl.gov/voro++
+.. _voro-home: https://math.lbl.gov/voro++
To use this package you must have the Voro++ library available on your
system.
@@ -2859,9 +2885,9 @@ A :doc:`dump vtk ` command which outputs snapshot info in the
`VTK format `_, enabling visualization by `Paraview `_ or
other visualization packages.
-.. _vtk: http://www.vtk.org
+.. _vtk: https://www.vtk.org
-.. _paraview: http://www.paraview.org
+.. _paraview: https://www.paraview.org
To use this package you must have VTK library available on your
system.
@@ -2898,11 +2924,13 @@ which discuss the `QuickFF `_ methodology.
.. _vanduyfhuys2015: https://doi.org/10.1002/jcc.23877
.. _vanduyfhuys2018: https://doi.org/10.1002/jcc.25173
-.. _quickff: http://molmod.github.io/QuickFF
+.. _quickff: https://molmod.github.io/QuickFF
.. _yaff: https://github.com/molmod/yaff
**Author:** Steven Vandenbrande.
+.. versionadded:: 1Feb2019
+
**Supporting info:**
* src/YAFF/README
diff --git a/doc/src/Python_examples.rst b/doc/src/Python_examples.rst
index fe5fe812c5..f795827230 100644
--- a/doc/src/Python_examples.rst
+++ b/doc/src/Python_examples.rst
@@ -43,26 +43,18 @@ Note that for AtomEye, you need version 3, and there is a line in the
scripts that specifies the path and name of the executable. See the
AtomEye web pages for more details:
-* `http://li.mit.edu/Archive/Graphics/A/ `_
-* `http://li.mit.edu/Archive/Graphics/A3/A3.html `_
+* `http://li.mit.edu/Archive/Graphics/A/ `_
-.. _atomeye: http://li.mit.edu/Archive/Graphics/A/
-
-.. _atomeye3: http://li.mit.edu/Archive/Graphics/A3/A3.html
-
-The latter link is to AtomEye 3 which has the scripting
-capability needed by these Python scripts.
+The latter link is to AtomEye 3 which has the scripting capability
+needed by these Python scripts.
Note that for PyMol, you need to have built and installed the
open-source version of PyMol in your Python, so that you can import it
from a Python script. See the PyMol web pages for more details:
- * `https://www.pymol.org `_
- * `https://github.com/schrodinger/pymol-open-source `_
-
-.. _pymolhome: https://www.pymol.org
-
-.. _pymolopen: https://github.com/schrodinger/pymol-open-source
+ * `https://www.pymol.org `_
+ * `https://github.com/schrodinger/pymol-open-source `_
The latter link is to the open-source version.
diff --git a/doc/src/Python_head.rst b/doc/src/Python_head.rst
index 3e84ed4506..3aab3a0d4b 100644
--- a/doc/src/Python_head.rst
+++ b/doc/src/Python_head.rst
@@ -18,17 +18,17 @@ together.
Python_error
Python_trouble
-If you are not familiar with `Python `_, it is a
+If you are not familiar with `Python `_, it is a
powerful scripting and programming language which can do almost
everything that compiled languages like C, C++, or Fortran can do in
fewer lines of code. It also comes with a large collection of add-on
modules for many purposes (either bundled or easily installed from
Python code repositories). The major drawback is slower execution speed
of the script code compared to compiled programming languages. But when
-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
+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.
diff --git a/doc/src/Run_options.rst b/doc/src/Run_options.rst
index d2d7f8c155..f3c7973197 100644
--- a/doc/src/Run_options.rst
+++ b/doc/src/Run_options.rst
@@ -495,7 +495,7 @@ run:
write_dump group-ID dumpstyle dumpfile arg1 arg2 ...
Note that the specified restartfile and dumpfile names may contain
-wild-card characters ("\*","%") as explained on the
+wild-card characters ("\*" or "%") as explained on the
:doc:`read_restart ` and :doc:`write_dump ` doc
pages. The use of "%" means that a parallel restart file and/or
parallel dump file can be read and/or written. Note that a filename
diff --git a/doc/src/Run_windows.rst b/doc/src/Run_windows.rst
index f29155a839..d36864b454 100644
--- a/doc/src/Run_windows.rst
+++ b/doc/src/Run_windows.rst
@@ -25,8 +25,8 @@ in parallel, follow these steps.
Download and install a compatible MPI library binary package:
-* for 32-bit Windows: `mpich2-1.4.1p1-win-ia32.msi `_
-* for 64-bit Windows: `mpich2-1.4.1p1-win-x86-64.msi `_
+* for 32-bit Windows: `mpich2-1.4.1p1-win-ia32.msi `_
+* for 64-bit Windows: `mpich2-1.4.1p1-win-x86-64.msi `_
The LAMMPS Windows installer packages will automatically adjust your
path for the default location of this MPI package. After the
diff --git a/doc/src/Speed_gpu.rst b/doc/src/Speed_gpu.rst
index 9015bff9ef..883bc9c7e3 100644
--- a/doc/src/Speed_gpu.rst
+++ b/doc/src/Speed_gpu.rst
@@ -39,7 +39,7 @@ toolkit software on your system (this is only tested on Linux
and unsupported on Windows):
* Check if you have an NVIDIA GPU: cat /proc/driver/nvidia/gpus/\*/information
-* Go to http://www.nvidia.com/object/cuda_get.html
+* Go to https://developer.nvidia.com/cuda-downloads
* Install a driver and toolkit appropriate for your system (SDK is not necessary)
* Run lammps/lib/gpu/nvc_get_devices (after building the GPU library, see below) to
list supported devices and properties
diff --git a/doc/src/Speed_intel.rst b/doc/src/Speed_intel.rst
index 6526f836b2..e3c3fc01f7 100644
--- a/doc/src/Speed_intel.rst
+++ b/doc/src/Speed_intel.rst
@@ -536,6 +536,6 @@ supported.
References
""""""""""
-* Brown, W.M., Carrillo, J.-M.Y., Mishra, B., Gavhane, N., Thakkar, F.M., De Kraker, A.R., Yamada, M., Ang, J.A., Plimpton, S.J., "Optimizing Classical Molecular Dynamics in LAMMPS," in Intel Xeon Phi Processor High Performance Programming: Knights Landing Edition, J. Jeffers, J. Reinders, A. Sodani, Eds. Morgan Kaufmann.
-* Brown, W. M., Semin, A., Hebenstreit, M., Khvostov, S., Raman, K., Plimpton, S.J. `Increasing Molecular Dynamics Simulation Rates with an 8-Fold Increase in Electrical Power Efficiency. `_ 2016 High Performance Computing, Networking, Storage and Analysis, SC16: International Conference (pp. 82-95).
+* Brown, W.M., Carrillo, J.-M.Y., Mishra, B., Gavhane, N., Thakkar, F.M., De Kraker, A.R., Yamada, M., Ang, J.A., Plimpton, S.J., "Optimizing Classical Molecular Dynamics in LAMMPS", in Intel Xeon Phi Processor High Performance Programming: Knights Landing Edition, J. Jeffers, J. Reinders, A. Sodani, Eds. Morgan Kaufmann.
+* Brown, W. M., Semin, A., Hebenstreit, M., Khvostov, S., Raman, K., Plimpton, S.J. `Increasing Molecular Dynamics Simulation Rates with an 8-Fold Increase in Electrical Power Efficiency. `_ 2016 High Performance Computing, Networking, Storage and Analysis, SC16: International Conference (pp. 82-95).
* Brown, W.M., Carrillo, J.-M.Y., Gavhane, N., Thakkar, F.M., Plimpton, S.J. Optimizing Legacy Molecular Dynamics Software with Directive-Based Offload. Computer Physics Communications. 2015. 195: p. 95-101.
diff --git a/doc/src/Speed_omp.rst b/doc/src/Speed_omp.rst
index 3d9cbe19e0..29c55df62f 100644
--- a/doc/src/Speed_omp.rst
+++ b/doc/src/Speed_omp.rst
@@ -97,7 +97,7 @@ sub-section.
A description of the multi-threading strategy used in the OPENMP
package and some performance examples are
-`presented here `_.
+`presented here `_.
Guidelines for best performance
"""""""""""""""""""""""""""""""
diff --git a/doc/src/Tools.rst b/doc/src/Tools.rst
index b57c91ffee..b70c7677e0 100644
--- a/doc/src/Tools.rst
+++ b/doc/src/Tools.rst
@@ -205,6 +205,7 @@ scripts are available:
whitespace.py # detects TAB characters and trailing whitespace
homepage.py # detects outdated LAMMPS homepage URLs (pointing to sandia.gov instead of lammps.org)
errordocs.py # detects deprecated error docs in header files
+ versiontags.py # detects .. versionadded:: or .. versionchanged:: with pending version date
The tools need to be given the main folder of the LAMMPS distribution
or individual file names as argument and will by default check them
@@ -397,7 +398,7 @@ ipp tool
------------------
The tools/ipp directory contains a Perl script ipp which can be used
-to facilitate the creation of a complicated file (say, a lammps input
+to facilitate the creation of a complicated file (say, a LAMMPS input
script or tools/createatoms input file) using a template file.
ipp was created and is maintained by Reese Jones (Sandia), rjones at
@@ -512,8 +513,8 @@ 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
-`_
+https://www.gnu.org/software/readline/
+
Additional commands
^^^^^^^^^^^^^^^^^^^
@@ -715,7 +716,7 @@ See the README.pdf file for more information.
These scripts were written by Arun Subramaniyan at Purdue Univ
(asubrama at purdue.edu).
-.. _matlabhome: http://www.mathworks.com
+.. _matlabhome: https://www.mathworks.com
----------
@@ -1046,7 +1047,7 @@ the binary file. This usually is a so-called little endian hardware
SWIG interface
--------------
-The `SWIG tool `_ offers a mostly automated way to
+The `SWIG tool `_ offers a mostly automated way to
incorporate compiled code modules into scripting languages. It
processes the function prototypes in C and generates wrappers for a wide
variety of scripting languages from it. Thus it can also be applied to
@@ -1126,7 +1127,7 @@ data passed or returned as pointers are included in the ``lammps.i``
file. So most of the functionality of the library interface should be
accessible. What works and what does not depends a bit on the
individual language for which the wrappers are built and how well SWIG
-supports those. The `SWIG documentation `_
+supports those. The `SWIG documentation `_
has very detailed instructions and recommendations.
Usage examples
diff --git a/doc/src/angle_coeff.rst b/doc/src/angle_coeff.rst
index 07048c1432..a9d7d0395b 100644
--- a/doc/src/angle_coeff.rst
+++ b/doc/src/angle_coeff.rst
@@ -10,7 +10,7 @@ Syntax
angle_coeff N args
-* N = angle type (see asterisk form below)
+* N = numeric angle type (see asterisk form below), or type label
* args = coefficients for one or more angle types
Examples
@@ -22,6 +22,9 @@ Examples
angle_coeff * 5.0
angle_coeff 2*10 5.0
+ labelmap angle 1 hydroxyl
+ angle_coeff hydroxyl 300.0 107.0
+
Description
"""""""""""
@@ -30,18 +33,24 @@ The number and meaning of the coefficients depends on the angle style.
Angle coefficients can also be set in the data file read by the
:doc:`read_data ` command or in a restart file.
-N can be specified in one of two ways. An explicit numeric value can
-be used, as in the first example above. Or a wild-card asterisk can be
-used to set the coefficients for multiple angle types. This takes the
-form "\*" or "\*n" or "n\*" or "m\*n". If N = the number of angle types,
-then an asterisk with no numeric values means all types from 1 to N. A
-leading asterisk means all types from 1 to n (inclusive). A trailing
-asterisk means all types from n to N (inclusive). A middle asterisk
-means all types from m to n (inclusive).
+:math:`N` can be specified in one of two ways. An explicit numeric
+value can be used, as in the first example above. Or :math:`N` can be a
+type label, which is an alphanumeric string defined by the
+:doc:`labelmap ` command or in a section of a data file read
+by the :doc:`read_data ` command.
-Note that using an :doc:`angle_coeff ` command can override a previous setting
-for the same angle type. For example, these commands set the coeffs
-for all angle types, then overwrite the coeffs for just angle type 2:
+For numeric values only, a wild-card asterisk can be used to set the
+coefficients for multiple angle types. This takes the form "\*" or
+"\*n" or "n\*" or "m\*n". If :math:`N` is the number of angle types,
+then an asterisk with no numeric values means all types from 1 to
+:math:`N`. A leading asterisk means all types from 1 to n (inclusive).
+A trailing asterisk means all types from n to :math:`N` (inclusive). A
+middle asterisk means all types from m to n (inclusive).
+
+Note that using an :doc:`angle_coeff ` command can
+override a previous setting for the same angle type. For example,
+these commands set the coeffs for all angle types, then overwrite the
+coeffs for just angle type 2:
.. code-block:: LAMMPS
@@ -49,11 +58,11 @@ for all angle types, then overwrite the coeffs for just angle type 2:
angle_coeff 2 50.0 107.0
A line in a data file that specifies angle coefficients uses the exact
-same format as the arguments of the :doc:`angle_coeff ` command in an input
-script, except that wild-card asterisks should not be used since
-coefficients for all N types must be listed in the file. For example,
-under the "Angle Coeffs" section of a data file, the line that
-corresponds to the first example above would be listed as
+same format as the arguments of the :doc:`angle_coeff `
+command in an input script, except that wild-card asterisks should not
+be used since coefficients for all :math:`N` types must be listed in the
+file. For example, under the "Angle Coeffs" section of a data file, the
+line that corresponds to the first example above would be listed as
.. parsed-literal::
@@ -61,15 +70,14 @@ corresponds to the first example above would be listed as
The :doc:`angle_style class2 ` is an exception to this
rule, in that an additional argument is used in the input script to
-allow specification of the cross-term coefficients. See its
-doc page for details.
+allow specification of the cross-term coefficients. See its doc page
+for details.
----------
The list of all angle styles defined in LAMMPS is given on the
:doc:`angle_style ` doc page. They are also listed in more
-compact form on the :ref:`Commands angle ` doc
-page.
+compact form on the :ref:`Commands angle ` doc page.
On either of those pages, click on the style to display the formula it
computes and its coefficients as specified by the associated
diff --git a/doc/src/angle_mesocnt.rst b/doc/src/angle_mesocnt.rst
index 94383929f8..2d7e98e737 100644
--- a/doc/src/angle_mesocnt.rst
+++ b/doc/src/angle_mesocnt.rst
@@ -24,7 +24,7 @@ Examples
Description
"""""""""""
-.. versionadded:: TBD
+.. versionadded:: 15Sep2022
The *mesocnt* angle style uses the potential
diff --git a/doc/src/bond_bpm_rotational.rst b/doc/src/bond_bpm_rotational.rst
index ae4fc3da64..5c43071274 100644
--- a/doc/src/bond_bpm_rotational.rst
+++ b/doc/src/bond_bpm_rotational.rst
@@ -138,15 +138,14 @@ the *overlay/pair* keyword. These settings require specific
restrictions. Further details can be found in the `:doc: how to
` page on BPMs.
-If the *store/local* keyword is used, this fix will track bonds that
+If the *store/local* keyword is used, an internal fix will track bonds that
break during the simulation. Whenever a bond breaks, data is processed
and transferred to an internal fix labeled *fix_ID*. This allows the
-local data to be accessed by other LAMMPS commands.
-Following any optional keyword/value arguments, a list of one or more
-attributes is specified. These include the IDs of the two atoms in
-the bond. The other attributes for the two atoms include the timestep
-during which the bond broke and the current/initial center of mass
-position of the two atoms.
+local data to be accessed by other LAMMPS commands. Following this optional
+keyword, a list of one or more attributes is specified. These include the
+IDs of the two atoms in the bond. The other attributes for the two atoms
+include the timestep during which the bond broke and the current/initial
+center of mass position of the two atoms.
Data is continuously accumulated over intervals of *N*
timesteps. At the end of each interval, all of the saved accumulated
@@ -177,29 +176,38 @@ Restart and other info
This bond style writes the reference state of each bond to
:doc:`binary restart files `. Loading a restart file will
-properly resume bonds.
+properly resume bonds. However, the reference state is NOT
+written to data files. Therefore reading a data file will not
+restore bonds and will cause their reference states to be redefined.
-The single() function of these pair styles returns 0.0 for the energy
-of a pairwise interaction, since energy is not conserved in these
-dissipative potentials. It also returns only the normal component of
-the pairwise interaction force.
-
-The accumulated data is not written to restart files and should be
-output before a restart file is written to avoid missing data.
-
-The internal fix calculates a local vector or local array depending on the
-number of input values. The length of the vector or number of rows in
-the array is the number of recorded, lost interactions. If a single
-input is specified, a local vector is produced. If two or more inputs
-are specified, a local array is produced where the number of columns =
-the number of inputs. The vector or array can be accessed by any
-command that uses local values from a compute as input. See the
-:doc:`Howto output ` page for an overview of LAMMPS
-output options.
+If the *store/local* option is used, an internal fix will calculate
+a local vector or local array depending on the number of input values.
+The length of the vector or number of rows in the array is the number
+of recorded, broken bonds. If a single input is specified, a local
+vector is produced. If two or more inputs are specified, a local array
+is produced where the number of columns = the number of inputs. The
+vector or array can be accessed by any command that uses local values
+from a compute as input. See the :doc:`Howto output ` page
+for an overview of LAMMPS output options.
The vector or array will be floating point values that correspond to
the specified attribute.
+The single() function of this bond style returns 0.0 for the energy
+of a bonded interaction, since energy is not conserved in these
+dissipative potentials. It also returns only the normal component of
+the bonded interaction force. However, the single() function also
+calculates 7 extra bond quantities. The first 4 are data from the
+reference state of the bond including the initial distance between particles
+:math:`r_0` followed by the :math:`x`, :math:`y`, and :math:`z` components
+of the initial unit vector pointing to particle I from particle J. The next 3
+quantities (5-7) are the :math:`x`, :math:`y`, and :math:`z` components
+of the total force, including normal and tangential contributions, acting
+on particle I.
+
+These extra quantities can be accessed by the :doc:`compute bond/local `
+command, as *b1*, *b2*, ..., *b7*\ .
+
Restrictions
""""""""""""
diff --git a/doc/src/bond_bpm_spring.rst b/doc/src/bond_bpm_spring.rst
index 1d2f12701d..de31357afe 100644
--- a/doc/src/bond_bpm_spring.rst
+++ b/doc/src/bond_bpm_spring.rst
@@ -103,15 +103,14 @@ the *overlay/pair* keyword. These settings require specific
restrictions. Further details can be found in the `:doc: how to
` page on BPMs.
-If the *store/local* keyword is used, this fix will track bonds that
+If the *store/local* keyword is used, an internal fix will track bonds that
break during the simulation. Whenever a bond breaks, data is processed
and transferred to an internal fix labeled *fix_ID*. This allows the
-local data to be accessed by other LAMMPS commands.
-Following any optional keyword/value arguments, a list of one or more
-attributes is specified. These include the IDs of the two atoms in
-the bond. The other attributes for the two atoms include the timestep
-during which the bond broke and the current/initial center of mass
-position of the two atoms.
+local data to be accessed by other LAMMPS commands. Following this optional
+keyword, a list of one or more attributes is specified. These include the
+IDs of the two atoms in the bond. The other attributes for the two atoms
+include the timestep during which the bond broke and the current/initial
+center of mass position of the two atoms.
Data is continuously accumulated over intervals of *N*
timesteps. At the end of each interval, all of the saved accumulated
@@ -141,28 +140,30 @@ Restart and other info
This bond style writes the reference state of each bond to
:doc:`binary restart files `. Loading a restart
-file will properly resume bonds.
+file will properly restore bonds. However, the reference state is NOT
+written to data files. Therefore reading a data file will not
+restore bonds and will cause their reference states to be redefined.
-The single() function of these pair styles returns 0.0 for the energy
-of a pairwise interaction, since energy is not conserved in these
-dissipative potentials.
-
-The accumulated data is not written to restart files and should be
-output before a restart file is written to avoid missing data.
-
-The internal fix calculates a local vector or local array depending on the
-number of input values. The length of the vector or number of rows in
-the array is the number of recorded, lost interactions. If a single
-input is specified, a local vector is produced. If two or more inputs
-are specified, a local array is produced where the number of columns =
-the number of inputs. The vector or array can be accessed by any
-command that uses local values from a compute as input. See the
-:doc:`Howto output ` page for an overview of LAMMPS
-output options.
+If the *store/local* option is used, an internal fix will calculate
+a local vector or local array depending on the number of input values.
+The length of the vector or number of rows in the array is the number
+of recorded, broken bonds. If a single input is specified, a local
+vector is produced. If two or more inputs are specified, a local array
+is produced where the number of columns = the number of inputs. The
+vector or array can be accessed by any command that uses local values
+from a compute as input. See the :doc:`Howto output ` page
+for an overview of LAMMPS output options.
The vector or array will be floating point values that correspond to
the specified attribute.
+The single() function of this bond style returns 0.0 for the energy
+of a bonded interaction, since energy is not conserved in these
+dissipative potentials. The single() function also calculates an
+extra bond quantity, the initial distance :math:`r_0`. This
+extra quantity can be accessed by the
+:doc:`compute bond/local ` command as *b1*\ .
+
Restrictions
""""""""""""
diff --git a/doc/src/bond_coeff.rst b/doc/src/bond_coeff.rst
index 84a949a018..f5b7f01e38 100644
--- a/doc/src/bond_coeff.rst
+++ b/doc/src/bond_coeff.rst
@@ -10,7 +10,7 @@ Syntax
bond_coeff N args
-* N = bond type (see asterisk form below)
+* N = numeric bond type (see asterisk form below), or type label
* args = coefficients for one or more bond types
Examples
@@ -21,7 +21,10 @@ Examples
bond_coeff 5 80.0 1.2
bond_coeff * 30.0 1.5 1.0 1.0
bond_coeff 1*4 30.0 1.5 1.0 1.0
- bond_coeff 1 harmonic 200.0 1.0
+ bond_coeff 1 harmonic 200.0 1.0 (for bond_style hybrid)
+
+ labelmap bond 5 carbonyl
+ bond_coeff carbonyl 80.0 1.2
Description
"""""""""""
@@ -31,14 +34,19 @@ The number and meaning of the coefficients depends on the bond style.
Bond coefficients can also be set in the data file read by the
:doc:`read_data ` command or in a restart file.
-N can be specified in one of two ways. An explicit numeric value can
-be used, as in the first example above. Or a wild-card asterisk can be
-used to set the coefficients for multiple bond types. This takes the
-form "\*" or "\*n" or "n\*" or "m\*n". If N = the number of bond types,
-then an asterisk with no numeric values means all types from 1 to N. A
+:math:`N` can be specified in one of several ways. An explicit numeric
+value can be used, as in the first example above. Or :math:`N` can be a
+type label, which is an alphanumeric string defined by the
+:doc:`labelmap ` command or in a section of a data file read
+by the :doc:`read_data ` command.
+
+For numeric values only, a wild-card asterisk can be used to set the
+coefficients for multiple bond types. This takes the form "\*" or "\*n"
+or "n\*" or "m\*n". If :math:`N` is the number of bond types, then an
+asterisk with no numeric values means all types from 1 to :math:`N`. A
leading asterisk means all types from 1 to n (inclusive). A trailing
-asterisk means all types from n to N (inclusive). A middle asterisk
-means all types from m to n (inclusive).
+asterisk means all types from n to :math:`N` (inclusive). A middle
+asterisk means all types from m to n (inclusive).
Note that using a bond_coeff command can override a previous setting
for the same bond type. For example, these commands set the coeffs
@@ -52,8 +60,8 @@ for all bond types, then overwrite the coeffs for just bond type 2:
A line in a data file that specifies bond coefficients uses the exact
same format as the arguments of the bond_coeff command in an input
script, except that wild-card asterisks should not be used since
-coefficients for all N types must be listed in the file. For example,
-under the "Bond Coeffs" section of a data file, the line that
+coefficients for all :math:`N` types must be listed in the file. For
+example, under the "Bond Coeffs" section of a data file, the line that
corresponds to the first example above would be listed as
.. parsed-literal::
diff --git a/doc/src/bond_mesocnt.rst b/doc/src/bond_mesocnt.rst
index 4631519440..8ed357a06b 100644
--- a/doc/src/bond_mesocnt.rst
+++ b/doc/src/bond_mesocnt.rst
@@ -22,7 +22,7 @@ Examples
Description
"""""""""""
-.. versionadded:: TBD
+.. versionadded:: 15Sep2022
The *mesocnt* bond style is a wrapper for the :doc:`harmonic
` style, and uses the potential
diff --git a/doc/src/commands_list.rst b/doc/src/commands_list.rst
index fdfb6d1d59..ee032bfd9e 100644
--- a/doc/src/commands_list.rst
+++ b/doc/src/commands_list.rst
@@ -56,6 +56,7 @@ Commands
kspace_modify
kspace_style
label
+ labelmap
lattice
log
mass
diff --git a/doc/src/compute_angmom_chunk.rst b/doc/src/compute_angmom_chunk.rst
index 2e98742772..ba3ec526cf 100644
--- a/doc/src/compute_angmom_chunk.rst
+++ b/doc/src/compute_angmom_chunk.rst
@@ -78,7 +78,7 @@ These values can be accessed by any command that uses global array
values from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output
options.
-The array values are "intensive." The array values will be in
+The array values are "intensive". The array values will be in
mass-velocity-distance :doc:`units `.
Restrictions
diff --git a/doc/src/compute_ave_sphere_atom.rst b/doc/src/compute_ave_sphere_atom.rst
index e5ed7e1437..ecb67ae7b5 100644
--- a/doc/src/compute_ave_sphere_atom.rst
+++ b/doc/src/compute_ave_sphere_atom.rst
@@ -35,6 +35,8 @@ Examples
Description
"""""""""""
+.. versionadded:: 7Jan2022
+
Define a computation that calculates the local mass density and
temperature for each atom based on its neighbors inside a spherical
cutoff. If an atom has :math:`M` neighbors, then its local mass density is
diff --git a/doc/src/compute_bond_local.rst b/doc/src/compute_bond_local.rst
index ed779d986e..f3fb752ebe 100644
--- a/doc/src/compute_bond_local.rst
+++ b/doc/src/compute_bond_local.rst
@@ -13,7 +13,7 @@ Syntax
* ID, group-ID are documented in :doc:`compute ` command
* bond/local = style name of this compute command
* one or more values may be appended
-* value = *dist* or *dx* or *dy* or *dz* or *engpot* or *force* or *fx* or *fy* or *fz* or *engvib* or *engrot* or *engtrans* or *omega* or *velvib* or *v_name*
+* value = *dist* or *dx* or *dy* or *dz* or *engpot* or *force* or *fx* or *fy* or *fz* or *engvib* or *engrot* or *engtrans* or *omega* or *velvib* or *v_name* or *bN*
.. parsed-literal::
@@ -29,6 +29,7 @@ Syntax
*omega* = magnitude of bond angular velocity
*velvib* = vibrational velocity along the bond length
*v_name* = equal-style variable with name (see below)
+ *bN* = bond style specific quantities for allowed N values
* zero or more keyword/args pairs may be appended
* keyword = *set*
@@ -47,7 +48,7 @@ Examples
compute 1 all bond/local engpot
compute 1 all bond/local dist engpot force
- compute 1 all bond/local dist fx fy fz
+ compute 1 all bond/local dist fx fy fz b1 b2
compute 1 all bond/local dist v_distsq set dist d
@@ -147,6 +148,19 @@ those quantities via the :doc:`compute reduce ` command
with thermo output, and the :doc:`fix ave/histo `
command will histogram the length\ :math:`^2` values and write them to a file.
+A bond style may define additional bond quantities which can be
+accessed as *b1* to *bN*, where N is defined by the bond style. Most
+bond styles do not define any additional quantities, so N = 0. An
+example of ones that do are the :doc:`BPM bond styles `
+which store the reference state between two particles. See
+individual bond styles for details.
+
+When using *bN* with bond style *hybrid*, the output will be the Nth
+quantity from the sub-style that computes the bonded interaction
+(based on bond type). If that sub-style does not define a *bN*,
+the output will be 0.0. The maximum allowed N is the maximum number
+of quantities provided by any sub-style.
+
----------
The local data stored by this command is generated by looping over all
diff --git a/doc/src/compute_born_matrix.rst b/doc/src/compute_born_matrix.rst
index 920ae46532..52bed6a357 100644
--- a/doc/src/compute_born_matrix.rst
+++ b/doc/src/compute_born_matrix.rst
@@ -182,7 +182,7 @@ by any command that uses global values from a compute as input. See
the :doc:`Howto output ` doc page for an overview of
LAMMPS output options.
-The array values calculated by this compute are all "extensive."
+The array values calculated by this compute are all "extensive".
Restrictions
""""""""""""
diff --git a/doc/src/compute_com.rst b/doc/src/compute_com.rst
index df5373293e..6fa3fda64c 100644
--- a/doc/src/compute_com.rst
+++ b/doc/src/compute_com.rst
@@ -49,7 +49,7 @@ accessed by indices 1--3 by any command that uses global vector values
from a compute as input. See the :doc:`Howto output ` doc
page for an overview of LAMMPS output options.
-The vector values are "intensive." The vector values will be in
+The vector values are "intensive". The vector values will be in
distance :doc:`units `.
Restrictions
diff --git a/doc/src/compute_com_chunk.rst b/doc/src/compute_com_chunk.rst
index a2df80d5d8..2556d97b09 100644
--- a/doc/src/compute_com_chunk.rst
+++ b/doc/src/compute_com_chunk.rst
@@ -77,7 +77,7 @@ values can be accessed by any command that uses global array values
from a compute as input. See the :doc:`Howto output ` doc
page for an overview of LAMMPS output options.
-The array values are "intensive." The array values will be in
+The array values are "intensive". The array values will be in
distance :doc:`units `.
Restrictions
diff --git a/doc/src/compute_damage_atom.rst b/doc/src/compute_damage_atom.rst
index b75a3ebc57..c4ccaca196 100644
--- a/doc/src/compute_damage_atom.rst
+++ b/doc/src/compute_damage_atom.rst
@@ -24,16 +24,18 @@ Description
"""""""""""
Define a computation that calculates the per-atom damage for each atom
-in a group. This is a quantity relevant for :doc:`Peridynamics models `. See `this document `_
-for an overview of LAMMPS commands for Peridynamics modeling.
+in a group. This is a quantity relevant for :doc:`Peridynamics models
+`. See `this document `_ for an
+overview of LAMMPS commands for Peridynamics modeling.
The "damage" of a Peridynamics particles is based on the bond breakage
between the particle and its neighbors. If all the bonds are broken
the particle is considered to be fully damaged.
-See the `PDLAMMPS user guide `_ for a formal
-definition of "damage" and more details about Peridynamics as it is
-implemented in LAMMPS.
+See the `PDLAMMPS user guide
+`_ for a
+formal definition of "damage" and more details about Peridynamics as it
+is implemented in LAMMPS.
This command can be used with all the Peridynamic pair styles.
@@ -53,8 +55,9 @@ The per-atom vector values are unitless numbers (damage) :math:`\ge 0.0`.
Restrictions
""""""""""""
-This compute is part of the PERI package. It is only enabled if
-LAMMPS was built with that package. See the :doc:`Build package ` page for more info.
+This compute is part of the PERI package. It is only enabled if LAMMPS
+was built with that package. See the :doc:`Build package
+` page for more info.
Related commands
""""""""""""""""
diff --git a/doc/src/compute_dilatation_atom.rst b/doc/src/compute_dilatation_atom.rst
index 8e3c86a4af..5eed50ed20 100644
--- a/doc/src/compute_dilatation_atom.rst
+++ b/doc/src/compute_dilatation_atom.rst
@@ -24,7 +24,8 @@ Description
"""""""""""
Define a computation that calculates the per-atom dilatation for each
-atom in a group. This is a quantity relevant for :doc:`Peridynamics models `. See `this document `_
+atom in a group. This is a quantity relevant for :doc:`Peridynamics
+models `. See `this document `_
for an overview of LAMMPS commands for Peridynamics modeling.
For small deformation, dilatation of is the measure of the volumetric
@@ -32,13 +33,14 @@ strain.
The dilatation :math:`\theta` for each peridynamic particle :math:`i` is
calculated as a sum over its neighbors with unbroken bonds, where the
-contribution of the :math:`ij` pair is a function of the change in bond length
-(versus the initial length in the reference state), the volume
-fraction of the particles and an influence function. See the
-`PDLAMMPS user guide `_ for
-a formal definition of dilatation.
+contribution of the :math:`ij` pair is a function of the change in bond
+length (versus the initial length in the reference state), the volume
+fraction of the particles and an influence function. See the `PDLAMMPS
+user guide `_
+for a formal definition of dilatation.
-This command can only be used with a subset of the Peridynamic :doc:`pair styles `: peri/lps, peri/ves and peri/eps.
+This command can only be used with a subset of the Peridynamic
+:doc:`pair styles `: peri/lps, peri/ves and peri/eps.
The dilatation value will be 0.0 for atoms not in the specified
compute group.
@@ -56,9 +58,9 @@ The per-atom vector values are unitless numbers :math:`(\theta \ge 0.0)`.
Restrictions
""""""""""""
-This compute is part of the PERI package. It is only enabled if
-LAMMPS was built with that package. See the
-:doc:`Build package ` page for more info.
+This compute is part of the PERI package. It is only enabled if LAMMPS
+was built with that package. See the :doc:`Build package
+` page for more info.
Related commands
""""""""""""""""
diff --git a/doc/src/compute_dipole.rst b/doc/src/compute_dipole.rst
index 7fb4b54fab..95c5e216f0 100644
--- a/doc/src/compute_dipole.rst
+++ b/doc/src/compute_dipole.rst
@@ -54,7 +54,7 @@ the computed dipole moment and a global vector of length 3 with the
dipole vector. See the :doc:`Howto output ` page for
an overview of LAMMPS output options.
-The computed values are "intensive." The array values will be in
+The computed values are "intensive". The array values will be in
dipole units (i.e., charge :doc:`units ` times distance
:doc:`units `).
diff --git a/doc/src/compute_dipole_chunk.rst b/doc/src/compute_dipole_chunk.rst
index 24e6442a63..504e6f20d0 100644
--- a/doc/src/compute_dipole_chunk.rst
+++ b/doc/src/compute_dipole_chunk.rst
@@ -86,7 +86,7 @@ chunk. These values can be accessed by any command that uses global
array values from a compute as input. See the :doc:`Howto output
` page for an overview of LAMMPS output options.
-The array values are "intensive." The array values will be in
+The array values are "intensive". The array values will be in
dipole units (i.e., charge :doc:`units ` times distance
:doc:`units `).
diff --git a/doc/src/compute_erotate_asphere.rst b/doc/src/compute_erotate_asphere.rst
index 44415c63cc..35691d8c9a 100644
--- a/doc/src/compute_erotate_asphere.rst
+++ b/doc/src/compute_erotate_asphere.rst
@@ -48,7 +48,7 @@ used by any command that uses a global scalar value from a compute as
input. See the :doc:`Howto output ` page for an
overview of LAMMPS output options.
-The scalar value calculated by this compute is "extensive." The
+The scalar value calculated by this compute is "extensive". The
scalar value will be in energy :doc:`units `.
Restrictions
diff --git a/doc/src/compute_erotate_rigid.rst b/doc/src/compute_erotate_rigid.rst
index 1e03a2316c..b1342bf15e 100644
--- a/doc/src/compute_erotate_rigid.rst
+++ b/doc/src/compute_erotate_rigid.rst
@@ -48,7 +48,7 @@ of all the rigid bodies). This value can be used by any command that
uses a global scalar value from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output
options.
-The scalar value calculated by this compute is "extensive." The
+The scalar value calculated by this compute is "extensive". The
scalar value will be in energy :doc:`units `.
Restrictions
diff --git a/doc/src/compute_erotate_sphere.rst b/doc/src/compute_erotate_sphere.rst
index 28b0052b89..aae37277a4 100644
--- a/doc/src/compute_erotate_sphere.rst
+++ b/doc/src/compute_erotate_sphere.rst
@@ -44,7 +44,7 @@ used by any command that uses a global scalar value from a compute as
input. See the :doc:`Howto output ` page for an
overview of LAMMPS output options.
-The scalar value calculated by this compute is "extensive." The
+The scalar value calculated by this compute is "extensive". The
scalar value will be in energy :doc:`units `.
Restrictions
diff --git a/doc/src/compute_event_displace.rst b/doc/src/compute_event_displace.rst
index f8911e1224..43881460f4 100644
--- a/doc/src/compute_event_displace.rst
+++ b/doc/src/compute_event_displace.rst
@@ -40,7 +40,7 @@ further than the threshold distance.
If the system is undergoing significant center-of-mass motion,
due to thermal motion, an external force, or an initial net momentum,
then this compute will not be able to distinguish that motion from
- local atom displacements and may generate "false positives."
+ local atom displacements and may generate "false positives".
Output info
"""""""""""
@@ -50,7 +50,7 @@ used by any command that uses a global scalar value from a compute as
input. See the :doc:`Howto output ` page for an
overview of LAMMPS output options.
-The scalar value calculated by this compute is "intensive." The
+The scalar value calculated by this compute is "intensive". The
scalar value will be a 0 or 1 as explained above.
Restrictions
diff --git a/doc/src/compute_fep.rst b/doc/src/compute_fep.rst
index e2de8d405b..481e4ead91 100644
--- a/doc/src/compute_fep.rst
+++ b/doc/src/compute_fep.rst
@@ -299,7 +299,7 @@ These output results can be used by any command that uses a global
scalar or vector from a compute as input. See the :doc:`Howto output ` page for an overview of LAMMPS output
options. For example, the computed values can be averaged using :doc:`fix ave/time `.
-The values calculated by this compute are "extensive."
+The values calculated by this compute are "extensive".
Restrictions
""""""""""""
diff --git a/doc/src/compute_fep_ta.rst b/doc/src/compute_fep_ta.rst
index 1fe89194ca..5b08d08718 100644
--- a/doc/src/compute_fep_ta.rst
+++ b/doc/src/compute_fep_ta.rst
@@ -34,6 +34,8 @@ Examples
Description
"""""""""""
+.. versionadded:: 4May2022
+
Define a computation that calculates the change in the free energy due
to a test-area (TA) perturbation :ref:`(Gloor) `. The test-area
approach can be used to determine the interfacial tension of the system
diff --git a/doc/src/compute_group_group.rst b/doc/src/compute_group_group.rst
index 87e855ae1e..b4eccf959f 100644
--- a/doc/src/compute_group_group.rst
+++ b/doc/src/compute_group_group.rst
@@ -140,7 +140,7 @@ vector values from a compute as input. See the
options.
Both the scalar and vector values calculated by this compute are
-"extensive." The scalar value will be in energy :doc:`units `.
+"extensive". The scalar value will be in energy :doc:`units `.
The vector values will be in force :doc:`units `.
Restrictions
diff --git a/doc/src/compute_gyration.rst b/doc/src/compute_gyration.rst
index 5610dd1d98..eaefc3abbb 100644
--- a/doc/src/compute_gyration.rst
+++ b/doc/src/compute_gyration.rst
@@ -69,7 +69,7 @@ vector values from a compute as input. See the :doc:`Howto output `, respectively.
Restrictions
diff --git a/doc/src/compute_gyration_shape.rst b/doc/src/compute_gyration_shape.rst
index 892677b0ba..2cbffbbdf4 100644
--- a/doc/src/compute_gyration_shape.rst
+++ b/doc/src/compute_gyration_shape.rst
@@ -78,7 +78,7 @@ vector values from a compute as input. See the
options.
The vector values calculated by this compute are
-"intensive." The first five vector values will be in
+"intensive". The first five vector values will be in
distance\ :math:`2` :doc:`units