diff --git a/SECURITY.md b/SECURITY.md
index 7b0ed1f560..e9b33afdcb 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -30,18 +30,19 @@ for unicode characters and only all-ASCII source code is accepted.
# Version Updates
-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
+LAMMPS follows a continuous release development model. We aim 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
+those tests are run on pull requests *before* merging to the `develop`
+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.
+`release` branch is fast-forwarded to that tag. This is often referred
+to as a patch release. Bug fixes and updates are
+applied first to the `develop` branch. Later, they appear in the `release`
+branch when the next patch release occurs.
+For stable releases, selected bug fixes, updates, and new functionality
+are pushed to the `stable` branch and a new stable tag is applied.
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://gle4md.org/ `_
**(Gao)**
Gao and Weber, Nuclear Instruments and Methods in Physics Research B 191 (2012) 504.
@@ -401,13 +401,13 @@ Bibliography
Hayre, and Farago, Comp Phys Comm, 185, 524 (2014)
**(Groot)**
- Groot and Warren, J Chem Phys, 107: 4423-4435 (1997). DOI: 10.1063/1.474784
+ Groot and Warren, J Chem Phys, 107: 4423-4435 (1997). DOI:10.1063/1.474784
**(Guenole)**
Guenole, Noehring, Vaid, Houlle, Xie, Prakash, Bitzek, Comput Mater Sci, 175, 109584 (2020).
**(Gullet)**
- Gullet, Wagner, Slepoy, SANDIA Report 2003-8782 (2003).
+ Gullet, Wagner, Slepoy, SANDIA Report 2003-8782 (2003). DOI:10.2172/918395
**(Guo)**
Guo and Thirumalai, Journal of Molecular Biology, 263, 323-43 (1996).
@@ -461,7 +461,7 @@ Bibliography
Hunt, Mol Simul, 42, 347 (2016).
**(IPI)**
- `http://epfl-cosmo.github.io/gle4md/index.html?page=ipi `_
+ `https://ipi-code.org/ `
**(IPI-CPC)**
Ceriotti, More and Manolopoulos, Comp Phys Comm, 185, 1019-1026 (2014).
@@ -605,16 +605,16 @@ Bibliography
I.\ Leven et al, J. Chem.Theory Comput. 12, 2896-905 (2016).
**(Li2013_POF)**
- Li, Hu, Wang, Ma, Zhou, Phys Fluids, 25: 072103 (2013). DOI: 10.1063/1.4812366.
+ Li, Hu, Wang, Ma, Zhou, Phys Fluids, 25: 072103 (2013). DOI:10.1063/1.4812366.
**(Li2014_JCP)**
- Li, Tang, Lei, Caswell, Karniadakis, J Comput Phys, 265: 113-127 (2014). DOI: 10.1016/j.jcp.2014.02.003.
+ Li, Tang, Lei, Caswell, Karniadakis, J Comput Phys, 265: 113-127 (2014). DOI:10.1016/j.jcp.2014.02.003.
**(Li2015_CC)**
- Li, Tang, Li, Karniadakis, Chem Commun, 51: 11038-11040 (2015). DOI: 10.1039/C5CC01684C.
+ Li, Tang, Li, Karniadakis, Chem Commun, 51: 11038-11040 (2015). DOI:10.1039/C5CC01684C.
**(Li2015_JCP)**
- Li, Yazdani, Tartakovsky, Karniadakis, J Chem Phys, 143: 014101 (2015). DOI: 10.1063/1.4923254.
+ Li, Yazdani, Tartakovsky, Karniadakis, J Chem Phys, 143: 014101 (2015). DOI:10.1063/1.4923254.
**(Lisal)**
M.\ Lisal, J.K. Brennan, J. Bonet Avalos, "Dissipative particle dynamics at isothermal, isobaric, isoenergetic, and isoenthalpic conditions using Shardlow-like splitting algorithms.",
@@ -733,8 +733,8 @@ Bibliography
**(Mishin)**
Mishin, Mehl, and Papaconstantopoulos, Acta Mater, 53, 4029 (2005).
-**(Mitchell and Finchham)**
- Mitchell, Finchham, J Phys Condensed Matter, 5, 1031-1038 (1993).
+**(Mitchell and Fincham)**
+ Mitchell, Fincham, J Phys Condensed Matter, 5, 1031-1038 (1993).
**(Mitchell2011)**
Mitchell. A non-local, ordinary-state-based viscoelasticity model for peridynamics. Sandia National Lab Report, 8064:1-28 (2011).
@@ -875,7 +875,7 @@ Bibliography
G.A. Tribello, M. Bonomi, D. Branduardi, C. Camilloni and G. Bussi, Comp. Phys. Comm 185, 604 (2014)
**(Paquay)**
- Paquay and Kusters, Biophys. J., 110, 6, (2016). preprint available at `arXiv:1411.3019 `_.
+ Paquay and Kusters, Biophys. J., 110, 6, (2016). preprint available at `arXiv:1411.3019 `_.
**(Park)**
Park, Schulten, J. Chem. Phys. 120 (13), 5946 (2004)
@@ -1373,7 +1373,7 @@ Bibliography
Zhu, Tajkhorshid, and Schulten, Biophys. J. 83, 154 (2002).
**(Ziegler)**
- J.F. Ziegler, J. P. Biersack and U. Littmark, "The Stopping and Range of Ions in Matter," Volume 1, Pergamon, 1985.
+ J.F. Ziegler, J. P. Biersack and U. Littmark, "The Stopping and Range of Ions in Matter", Volume 1, Pergamon, 1985.
**(Zimmerman2004)**
Zimmerman, JA; Webb, EB; Hoyt, JJ;. Jones, RE; Klein, PA; Bammann, DJ, "Calculation of stress in atomistic simulation." Special Issue of Modelling and Simulation in Materials Science and Engineering (2004),12:S319.
diff --git a/doc/src/Build_basics.rst b/doc/src/Build_basics.rst
index 9ef209b3b3..91b23f000f 100644
--- a/doc/src/Build_basics.rst
+++ b/doc/src/Build_basics.rst
@@ -276,7 +276,7 @@ LAMMPS.
Parallel build (see ``src/MAKE/Makefile.mpi``):
- .. code-block:: bash
+ .. code-block:: make
CC = mpicxx
CCFLAGS = -g -O3
@@ -296,7 +296,7 @@ LAMMPS.
If compilation stops with a message like the following:
- .. code-block::
+ .. code-block:: output
g++ -g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I../STUBS -c ../main.cpp
In file included from ../pointers.h:24:0,
diff --git a/doc/src/Build_development.rst b/doc/src/Build_development.rst
index a5deca4a39..c2645a2118 100644
--- a/doc/src/Build_development.rst
+++ b/doc/src/Build_development.rst
@@ -140,7 +140,7 @@ of the LAMMPS project on GitHub.
The unit testing facility is integrated into the CMake build process
of the LAMMPS source code distribution itself. It can be enabled by
setting ``-D ENABLE_TESTING=on`` during the CMake configuration step.
-It requires the `YAML `_ library and development
+It requires the `YAML `_ library and development
headers (if those are not found locally a recent version will be
downloaded and compiled along with LAMMPS and the test program) to
compile and will download and compile a specific recent version of the
@@ -154,32 +154,48 @@ for implementing the tests.
framework are more strict than for the main part of LAMMPS. For
example the default GNU C++ and Fortran compilers of RHEL/CentOS 7.x
(version 4.8.x) are not sufficient. The CMake configuration will try
- to detect compatible versions and either skip incompatible tests or
- stop with an error.
+ to detect incompatible versions and either skip incompatible tests or
+ stop with an error. Also the number of tests will depend on
+ installed LAMMPS packages, development environment, operating system,
+ and configuration settings.
After compilation is complete, the unit testing is started in the build
folder using the ``ctest`` command, which is part of the CMake software.
-The output of this command will be looking something like this::
+The output of this command will be looking something like this:
- [...]$ ctest
- Test project /home/akohlmey/compile/lammps/build-testing
- Start 1: MolPairStyle:hybrid-overlay
- 1/109 Test #1: MolPairStyle:hybrid-overlay ......... Passed 0.02 sec
- Start 2: MolPairStyle:hybrid
- 2/109 Test #2: MolPairStyle:hybrid ................. Passed 0.01 sec
- Start 3: MolPairStyle:lj_class2
- [...]
- Start 107: PotentialFileReader
- 107/109 Test #107: PotentialFileReader ................ Passed 0.04 sec
- Start 108: EIMPotentialFileReader
- 108/109 Test #108: EIMPotentialFileReader ............. Passed 0.03 sec
- Start 109: TestSimpleCommands
- 109/109 Test #109: TestSimpleCommands ................. Passed 0.02 sec
+.. code-block:: console
- 100% tests passed, 0 tests failed out of 26
+ $ ctest
+ Test project /home/akohlmey/compile/lammps/build-testing
+ Start 1: RunLammps
+ 1/563 Test #1: RunLammps .......................................... Passed 0.28 sec
+ Start 2: HelpMessage
+ 2/563 Test #2: HelpMessage ........................................ Passed 0.06 sec
+ Start 3: InvalidFlag
+ 3/563 Test #3: InvalidFlag ........................................ Passed 0.06 sec
+ Start 4: Tokenizer
+ 4/563 Test #4: Tokenizer .......................................... Passed 0.05 sec
+ Start 5: MemPool
+ 5/563 Test #5: MemPool ............................................ Passed 0.05 sec
+ Start 6: ArgUtils
+ 6/563 Test #6: ArgUtils ........................................... Passed 0.05 sec
+ [...]
+ Start 561: ImproperStyle:zero
+ 561/563 Test #561: ImproperStyle:zero ................................. Passed 0.07 sec
+ Start 562: TestMliapPyUnified
+ 562/563 Test #562: TestMliapPyUnified ................................. Passed 0.16 sec
+ Start 563: TestPairList
+ 563/563 Test #563: TestPairList ....................................... Passed 0.06 sec
- Total Test time (real) = 25.57 sec
+ 100% tests passed, 0 tests failed out of 563
+ Label Time Summary:
+ generated = 0.85 sec*proc (3 tests)
+ noWindows = 4.16 sec*proc (2 tests)
+ slow = 78.33 sec*proc (67 tests)
+ unstable = 28.23 sec*proc (34 tests)
+
+ Total Test time (real) = 132.34 sec
The ``ctest`` command has many options, the most important ones are:
@@ -210,11 +226,13 @@ Fortran) and testing different aspects of the LAMMPS software and its features.
The tests will adapt to the compilation settings of LAMMPS, so that tests
will be skipped if prerequisite features are not available in LAMMPS.
-.. note::
+.. admonition:: Work in Progress
+ :class: note
The unit test framework was added in spring 2020 and is under active
development. The coverage is not complete and will be expanded over
- time.
+ time. Preference is given to parts of the code base that are easy to
+ test or commonly used.
Tests for styles of the same kind of style (e.g. pair styles or bond
styles) are performed with the same test executable using different
@@ -248,9 +266,9 @@ the CMake option ``-D BUILD_MPI=off`` can significantly speed up testing,
since this will skip the MPI initialization for each test run.
Below is an example command and output:
-.. parsed-literal::
+.. code-block:: console
- [tests]$ test_pair_style mol-pair-lj_cut.yaml
+ $ test_pair_style mol-pair-lj_cut.yaml
[==========] Running 6 tests from 1 test suite.
[----------] Global test environment set-up.
[----------] 6 tests from PairStyle
@@ -530,7 +548,7 @@ commands like the following:
.. code-block:: bash
- $ clang-format -i some_file.cpp
+ clang-format -i some_file.cpp
The following target are available for both, GNU make and CMake:
@@ -539,3 +557,19 @@ The following target are available for both, GNU make and CMake:
make format-src # apply clang-format to all files in src and the package folders
make format-tests # apply clang-format to all files in the unittest tree
+
+----------
+
+.. _gh-cli:
+
+GitHub command line interface
+-----------------------------
+
+GitHub is developing a `tool for the command line
+`_ that interacts with the GitHub website via a
+command called ``gh``. This can be extremely convenient when working
+with a Git repository hosted on GitHub (like LAMMPS). It is thus highly
+recommended to install it when doing LAMMPS development.
+
+The capabilities of the ``gh`` command is continually expanding, so
+please see the documentation at https://cli.github.com/manual/
diff --git a/doc/src/Build_extras.rst b/doc/src/Build_extras.rst
index 99051110b3..c0a40deeb1 100644
--- a/doc/src/Build_extras.rst
+++ b/doc/src/Build_extras.rst
@@ -12,11 +12,11 @@ in addition to
- Traditional make
* - .. code-block:: bash
- $ cmake -D PKG_NAME=yes
+ cmake -D PKG_NAME=yes
- - .. code-block:: bash
+ - .. code-block:: console
- $ make yes-name
+ make yes-name
as described on the :doc:`Build_package ` page.
@@ -28,14 +28,16 @@ You may need to tell LAMMPS where it is found on your system.
This is the list of packages that may require additional steps.
+.. this list must be kept in sync with its counterpart in Build_package.rst
.. table_from_list::
:columns: 6
* :ref:`ADIOS `
* :ref:`ATC `
* :ref:`AWPMD `
- * :ref:`COLVARS `
+ * :ref:`COLVARS `
* :ref:`COMPRESS `
+ * :ref:`ELECTRODE `
* :ref:`GPU `
* :ref:`H5MD `
* :ref:`INTEL `
@@ -148,7 +150,9 @@ CMake build
* sm_60 or sm_61 for Pascal (supported since CUDA 8)
* sm_70 for Volta (supported since CUDA 9)
* sm_75 for Turing (supported since CUDA 10)
-* sm_80 for Ampere (supported since CUDA 11)
+* sm_80 or sm_86 for Ampere (supported since CUDA 11, sm_86 since CUDA 11.1)
+* sm_89 for Lovelace (supported since CUDA 11.8)
+* sm_90 for Hopper (supported since CUDA 12.0)
A more detailed list can be found, for example,
at `Wikipedia's CUDA article `_
@@ -221,10 +225,10 @@ script with the specified args:
.. code-block:: bash
- $ make lib-gpu # print help message
- $ make lib-gpu args="-b" # build GPU library with default Makefile.linux
- $ make lib-gpu args="-m xk7 -p single -o xk7.single" # create new Makefile.xk7.single, altered for single-precision
- $ make lib-gpu args="-m mpi -a sm_60 -p mixed -b" # build GPU library with mixed precision and P100 using other settings in Makefile.mpi
+ make lib-gpu # print help message
+ make lib-gpu args="-b" # build GPU library with default Makefile.linux
+ make lib-gpu args="-m xk7 -p single -o xk7.single" # create new Makefile.xk7.single, altered for single-precision
+ make lib-gpu args="-m mpi -a sm_60 -p mixed -b" # build GPU library with mixed precision and P100 using other settings in Makefile.mpi
Note that this procedure starts with a Makefile.machine in lib/gpu, as
specified by the "-m" switch. For your convenience, machine makefiles
@@ -337,13 +341,13 @@ minutes to hours) to build. Of course you only need to do that once.)
.. code-block:: bash
- $ make lib-kim # print help message
- $ make lib-kim args="-b " # (re-)install KIM API lib with only example models
- $ make lib-kim args="-b -a Glue_Ercolessi_Adams_Al__MO_324507536345_001" # ditto plus one model
- $ make lib-kim args="-b -a everything" # install KIM API lib with all models
- $ make lib-kim args="-n -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # add one model or model driver
- $ make lib-kim args="-p /usr/local" # use an existing KIM API installation at the provided location
- $ make lib-kim args="-p /usr/local -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # ditto but add one model or driver
+ make lib-kim # print help message
+ make lib-kim args="-b " # (re-)install KIM API lib with only example models
+ make lib-kim args="-b -a Glue_Ercolessi_Adams_Al__MO_324507536345_001" # ditto plus one model
+ make lib-kim args="-b -a everything" # install KIM API lib with all models
+ make lib-kim args="-n -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # add one model or model driver
+ make lib-kim args="-p /usr/local" # use an existing KIM API installation at the provided location
+ make lib-kim args="-p /usr/local -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # ditto but add one model or driver
When using the "-b " option, the KIM library is built using its native
cmake build system. The ``lib/kim/Install.py`` script supports a
@@ -355,7 +359,7 @@ minutes to hours) to build. Of course you only need to do that once.)
.. code-block:: bash
- $ CMAKE=cmake3 CXX=g++-11 CC=gcc-11 FC=gfortran-11 make lib-kim args="-b " # (re-)install KIM API lib using cmake3 and gnu v11 compilers with only example models
+ CMAKE=cmake3 CXX=g++-11 CC=gcc-11 FC=gfortran-11 make lib-kim args="-b " # (re-)install KIM API lib using cmake3 and gnu v11 compilers with only example models
Settings for debugging OpenKIM web queries discussed below need to
be applied by adding them to the ``LMP_INC`` variable through
@@ -808,11 +812,11 @@ library.
.. code-block:: bash
- $ make lib-latte # print help message
- $ make lib-latte args="-b" # download and build in lib/latte/LATTE-master
- $ make lib-latte args="-p $HOME/latte" # use existing LATTE installation in $HOME/latte
- $ make lib-latte args="-b -m gfortran" # download and build in lib/latte and
- # copy Makefile.lammps.gfortran to Makefile.lammps
+ make lib-latte # print help message
+ make lib-latte args="-b" # download and build in lib/latte/LATTE-master
+ make lib-latte args="-p $HOME/latte" # use existing LATTE installation in $HOME/latte
+ make lib-latte args="-b -m gfortran" # download and build in lib/latte and
+ # copy Makefile.lammps.gfortran to Makefile.lammps
Note that 3 symbolic (soft) links, ``includelink`` and ``liblink``
and ``filelink.o``, are created in ``lib/latte`` to point to
@@ -911,12 +915,12 @@ more details.
.. code-block:: bash
- $ make lib-mscg # print help message
- $ make lib-mscg args="-b -m serial" # download and build in lib/mscg/MSCG-release-master
- # with the settings compatible with "make serial"
- $ make lib-mscg args="-b -m mpi" # download and build in lib/mscg/MSCG-release-master
- # with the settings compatible with "make mpi"
- $ make lib-mscg args="-p /usr/local/mscg-release" # use the existing MS-CG installation in /usr/local/mscg-release
+ make lib-mscg # print help message
+ make lib-mscg args="-b -m serial" # download and build in lib/mscg/MSCG-release-master
+ # with the settings compatible with "make serial"
+ make lib-mscg args="-b -m mpi" # download and build in lib/mscg/MSCG-release-master
+ # with the settings compatible with "make mpi"
+ make lib-mscg args="-p /usr/local/mscg-release" # use the existing MS-CG installation in /usr/local/mscg-release
Note that 2 symbolic (soft) links, ``includelink`` and ``liblink``,
will be created in ``lib/mscg`` to point to the MS-CG
@@ -968,10 +972,10 @@ POEMS package
.. code-block:: bash
- $ make lib-poems # print help message
- $ make lib-poems args="-m serial" # build with GNU g++ compiler (settings as with "make serial")
- $ make lib-poems args="-m mpi" # build with default MPI C++ compiler (settings as with "make mpi")
- $ make lib-poems args="-m icc" # build with Intel icc compiler
+ make lib-poems # print help message
+ make lib-poems args="-m serial" # build with GNU g++ compiler (settings as with "make serial")
+ make lib-poems args="-m mpi" # build with default MPI C++ compiler (settings as with "make mpi")
+ make lib-poems args="-m icc" # build with Intel icc compiler
The build should produce two files: ``lib/poems/libpoems.a`` and
``lib/poems/Makefile.lammps``. The latter is copied from an
@@ -1057,10 +1061,10 @@ binary package provided by your operating system.
.. code-block:: bash
- $ make lib-voronoi # print help message
- $ make lib-voronoi args="-b" # download and build the default version in lib/voronoi/voro++-
- $ make lib-voronoi args="-p $HOME/voro++" # use existing Voro++ installation in $HOME/voro++
- $ make lib-voronoi args="-b -v voro++0.4.6" # download and build the 0.4.6 version in lib/voronoi/voro++-0.4.6
+ make lib-voronoi # print help message
+ make lib-voronoi args="-b" # download and build the default version in lib/voronoi/voro++-
+ make lib-voronoi args="-p $HOME/voro++" # use existing Voro++ installation in $HOME/voro++
+ make lib-voronoi args="-b -v voro++0.4.6" # download and build the 0.4.6 version in lib/voronoi/voro++-0.4.6
Note that 2 symbolic (soft) links, ``includelink`` and
``liblink``, are created in lib/voronoi to point to the Voro++
@@ -1101,13 +1105,13 @@ systems.
.. code-block:: bash
- $ make yes-adios
+ make yes-adios
otherwise, set ADIOS2_DIR environment variable when turning on the package:
.. code-block:: bash
- $ ADIOS2_DIR=path make yes-adios # path is where ADIOS 2.x is installed
+ ADIOS2_DIR=path make yes-adios # path is where ADIOS 2.x is installed
----------
@@ -1136,10 +1140,10 @@ The ATC package requires the MANYBODY package also be installed.
.. code-block:: bash
- $ make lib-atc # print help message
- $ make lib-atc args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
- $ make lib-atc args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
- $ make lib-atc args="-m icc" # build with Intel icc compiler
+ make lib-atc # print help message
+ make lib-atc args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
+ make lib-atc args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
+ make lib-atc args="-m icc" # build with Intel icc compiler
The build should produce two files: ``lib/atc/libatc.a`` and
``lib/atc/Makefile.lammps``. The latter is copied from an
@@ -1158,17 +1162,17 @@ The ATC package requires the MANYBODY package also be installed.
.. code-block:: bash
- $ make lib-linalg # print help message
- $ make lib-linalg args="-m serial" # build with GNU Fortran compiler (settings as with "make serial")
- $ make lib-linalg args="-m mpi" # build with default MPI Fortran compiler (settings as with "make mpi")
- $ make lib-linalg args="-m gfortran" # build with GNU Fortran compiler
+ make lib-linalg # print help message
+ make lib-linalg args="-m serial" # build with GNU C++ compiler (settings as with "make serial")
+ make lib-linalg args="-m mpi" # build with default MPI C++ compiler (settings as with "make mpi")
+ make lib-linalg args="-m g++" # build with GNU Fortran compiler
----------
.. _awpmd:
AWPMD package
-------------------
+-------------
.. tabs::
@@ -1187,10 +1191,10 @@ AWPMD package
.. code-block:: bash
- $ make lib-awpmd # print help message
- $ make lib-awpmd args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
- $ make lib-awpmd args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
- $ make lib-awpmd args="-m icc" # build with Intel icc compiler
+ make lib-awpmd # print help message
+ make lib-awpmd args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
+ make lib-awpmd args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
+ make lib-awpmd args="-m icc" # build with Intel icc compiler
The build should produce two files: ``lib/awpmd/libawpmd.a`` and
``lib/awpmd/Makefile.lammps``. The latter is copied from an
@@ -1209,21 +1213,20 @@ AWPMD package
.. code-block:: bash
- $ make lib-linalg # print help message
- $ make lib-linalg args="-m serial" # build with GNU Fortran compiler (settings as with "make serial")
- $ make lib-linalg args="-m mpi" # build with default MPI Fortran compiler (settings as with "make mpi")
- $ make lib-linalg args="-m gfortran" # build with GNU Fortran compiler
+ make lib-linalg # print help message
+ make lib-linalg args="-m serial" # build with GNU C++ compiler (settings as with "make serial")
+ make lib-linalg args="-m mpi" # build with default MPI C++ compiler (settings as with "make mpi")
+ make lib-linalg args="-m g++" # build with GNU C++ compiler
----------
-.. _colvars:
+.. _colvar:
COLVARS package
----------------------------------------
+---------------
-This package includes the `Colvars library
-`_ into the LAMMPS distribution, which can
-be built for the most part with all major versions of the C++ language.
+This package enables the use of the `Colvars `_
+module included in the LAMMPS source distribution.
.. tabs::
@@ -1250,10 +1253,10 @@ be built for the most part with all major versions of the C++ language.
.. code-block:: bash
- $ make lib-colvars # print help message
- $ make lib-colvars args="-m serial" # build with GNU g++ compiler (settings as with "make serial")
- $ make lib-colvars args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
- $ make lib-colvars args="-m g++-debug" # build with GNU g++ compiler and colvars debugging enabled
+ make lib-colvars # print help message
+ make lib-colvars args="-m serial" # build with GNU g++ compiler (settings as with "make serial")
+ make lib-colvars args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
+ make lib-colvars args="-m g++-debug" # build with GNU g++ compiler and colvars debugging enabled
The "machine" argument of the "-m" flag is used to find a
Makefile.machine to use as build recipe. If it does not already
@@ -1265,8 +1268,8 @@ be built for the most part with all major versions of the C++ language.
.. code-block:: bash
- $ COLVARS_DEBUG=yes make lib-colvars args="-m machine" # Build with debug code (much slower)
- $ COLVARS_LEPTON=no make lib-colvars args="-m machine" # Build without Lepton (included otherwise)
+ COLVARS_DEBUG=yes make lib-colvars args="-m machine" # Build with debug code (much slower)
+ COLVARS_LEPTON=no make lib-colvars args="-m machine" # Build without Lepton (included otherwise)
The build should produce two files: the library ``lib/colvars/libcolvars.a``
(which also includes Lepton objects if enabled) and the specification file
@@ -1300,9 +1303,9 @@ This package depends on the KSPACE package.
.. code-block:: bash
- $ make lib-electrode # print help message
- $ make lib-electrode args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
- $ make lib-electrode args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
+ make lib-electrode # print help message
+ make lib-electrode args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
+ make lib-electrode args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
Note that the ``Makefile.lammps`` file has settings for the BLAS
@@ -1313,10 +1316,10 @@ This package depends on the KSPACE package.
.. code-block:: bash
- $ make lib-linalg # print help message
- $ make lib-linalg args="-m serial" # build with GNU Fortran compiler (settings as with "make serial")
- $ make lib-linalg args="-m mpi" # build with default MPI Fortran compiler (settings as with "make mpi")
- $ make lib-linalg args="-m gfortran" # build with GNU Fortran compiler
+ make lib-linalg # print help message
+ make lib-linalg args="-m serial" # build with GNU Fortran compiler (settings as with "make serial")
+ make lib-linalg args="-m mpi" # build with default MPI Fortran compiler (settings as with "make mpi")
+ make lib-linalg args="-m gfortran" # build with GNU Fortran compiler
The package itself is activated with ``make yes-KSPACE`` and
``make yes-ELECTRODE``
@@ -1356,8 +1359,8 @@ at: `https://github.com/ICAMS/lammps-user-pace/ `_ for compiling software on
+ macOS, so you have likely installed it to compile LAMMPS. Their
+ compiler is based on `Clang `, but while it
+ is capable of processing OpenMP directives, the necessary header
+ files and OpenMP runtime library are missing. The `R developers
+ ` have figured out a way to build those
+ in a compatible fashion. One can download them from
+ `https://mac.r-project.org/openmp/
+ `_. Simply adding those files as
+ instructed enables the Xcode C++ compiler to compile LAMMPS with ``-D
+ BUILD_OMP=yes``.
+
----------
.. _qmmm:
@@ -1887,10 +1906,10 @@ verified to work in February 2020 with Quantum Espresso versions 6.3 to
.. code-block:: bash
- $ make lib-qmmm # print help message
- $ make lib-qmmm args="-m serial" # build with GNU Fortran compiler (settings as in "make serial")
- $ make lib-qmmm args="-m mpi" # build with default MPI compiler (settings as in "make mpi")
- $ make lib-qmmm args="-m gfortran" # build with GNU Fortran compiler
+ make lib-qmmm # print help message
+ make lib-qmmm args="-m serial" # build with GNU Fortran compiler (settings as in "make serial")
+ make lib-qmmm args="-m mpi" # build with default MPI compiler (settings as in "make mpi")
+ make lib-qmmm args="-m gfortran" # build with GNU Fortran compiler
The build should produce two files: ``lib/qmmm/libqmmm.a`` and
``lib/qmmm/Makefile.lammps``. The latter is copied from an
@@ -2028,9 +2047,9 @@ Eigen3 is a template library, so you do not need to build it.
.. code-block:: bash
- $ make lib-smd # print help message
- $ make lib-smd args="-b" # download to lib/smd/eigen3
- $ make lib-smd args="-p /usr/include/eigen3" # use existing Eigen installation in /usr/include/eigen3
+ make lib-smd # print help message
+ make lib-smd args="-b" # download to lib/smd/eigen3
+ make lib-smd args="-p /usr/include/eigen3" # use existing Eigen installation in /usr/include/eigen3
Note that a symbolic (soft) link named ``includelink`` is created
in ``lib/smd`` to point to the Eigen dir. When LAMMPS builds it
diff --git a/doc/src/Build_link.rst b/doc/src/Build_link.rst
index 5255620231..79868de83c 100644
--- a/doc/src/Build_link.rst
+++ b/doc/src/Build_link.rst
@@ -209,7 +209,7 @@ You can verify whether all required shared libraries are found with the
.. code-block:: bash
- $ LD_LIBRARY_PATH=/home/user/lammps/src ldd caller
+ LD_LIBRARY_PATH=/home/user/lammps/src ldd caller
linux-vdso.so.1 (0x00007ffe729e0000)
liblammps.so => /home/user/lammps/src/liblammps.so (0x00007fc91bb9e000)
libstdc++.so.6 => /lib64/libstdc++.so.6 (0x00007fc91b984000)
@@ -222,7 +222,7 @@ If a required library is missing, you would get a 'not found' entry:
.. code-block:: bash
- $ ldd caller
+ ldd caller
linux-vdso.so.1 (0x00007ffd672fe000)
liblammps.so => not found
libstdc++.so.6 => /usr/lib64/libstdc++.so.6 (0x00007fb7c7e86000)
diff --git a/doc/src/Build_manual.rst b/doc/src/Build_manual.rst
index 90633d0811..9b0f00276c 100644
--- a/doc/src/Build_manual.rst
+++ b/doc/src/Build_manual.rst
@@ -48,18 +48,15 @@ Build using GNU make
The LAMMPS manual is written in `reStructuredText `_ format which
can be translated to different output format using the `Sphinx
-`_ document generator tool. It also incorporates programmer
-documentation extracted from the LAMMPS C++ sources through the `Doxygen
-`_ program. Currently the translation to HTML, PDF
-(via LaTeX), ePUB (for many e-book readers) and MOBI (for Amazon Kindle
-readers) are supported. For that to work a Python 3 interpreter, the
-``doxygen`` tools and internet access to download additional files and
-tools are required. This download is usually only required once or
-after the documentation folder is returned to a pristine state with
-``make clean-all``.
-
-.. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html
-.. _sphinx: https://www.sphinx-doc.org
+`_ document generator tool. It also
+incorporates programmer documentation extracted from the LAMMPS C++
+sources through the `Doxygen `_ program. Currently
+the translation to HTML, PDF (via LaTeX), ePUB (for many e-book readers)
+and MOBI (for Amazon Kindle readers) are supported. For that to work a
+Python 3 interpreter, the ``doxygen`` tools and internet access to
+download additional files and tools are required. This download is
+usually only required once or after the documentation folder is returned
+to a pristine state with ``make clean-all``.
For the documentation build a python virtual environment is set up in
the folder ``doc/docenv`` and various python packages are installed into
@@ -128,38 +125,29 @@ common setups:
.. code-block:: bash
- sudo apt-get install python-virtualenv git doxygen
+ sudo apt-get install git doxygen
.. tab:: RHEL or CentOS (Version 7.x)
.. code-block:: bash
- sudo yum install python3-virtualenv git doxygen
+ sudo yum install git doxygen
.. tab:: Fedora or RHEL/CentOS (8.x or later)
.. code-block:: bash
- sudo dnf install python3-virtualenv git doxygen
+ sudo dnf install git doxygen
- .. tab:: MacOS X
+ .. tab:: macOS
*Python 3*
- Download the latest Python 3 MacOS X package from
+ If Python 3 is not available on your macOS system, you can
+ download the latest Python 3 macOS package from
`https://www.python.org `_ and install it.
This will install both Python 3 and pip3.
- *virtualenv*
-
- Once Python 3 is installed, open a Terminal and type
-
- .. code-block:: bash
-
- pip3 install virtualenv
-
- This will install virtualenv from the Python Package Index.
-
Prerequisites for PDF
---------------------
@@ -179,7 +167,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/ `_
+installed. `https://calibre-ebook.com/ `_
Typing ``make mobi`` will first create the ePUB file and then convert
it. On the Kindle readers in particular, you also have support for PDF
files, so you could download and view the PDF version as an alternative.
@@ -219,9 +207,20 @@ be multiple tests run automatically:
- A test that only standard, printable ASCII text characters are used.
This runs the command ``env LC_ALL=C grep -n '[^ -~]' src/*.rst`` and
thus prints all offending lines with filename and line number
- prepended to the screen. Special characters like the Angstrom
- :math:`\mathrm{\mathring{A}}` should be typeset with embedded math
- (like this ``:math:`\mathrm{\mathring{A}}```\ ).
+ prepended to the screen. Special characters like Greek letters
+ (:math:`\alpha~~\sigma~~\epsilon`), super- or subscripts
+ (:math:`x^2~~\mathrm{U}_{LJ}`), mathematical expressions
+ (:math:`\frac{1}{2}\mathrm{N}~~x\to\infty`), or the Angstrom symbol
+ (:math:`\AA`) should be typeset with embedded LaTeX (like this
+ ``:math:`\alpha \sigma \epsilon```, ``:math:`x^2 \mathrm{E}_{LJ}```,
+ ``:math:`\frac{1}{2}\mathrm{N} x\to\infty```, or ``:math:`\AA```\ ).
+
+- Embedded LaTeX is rendered in HTML output with `MathJax
+ `_ and in PDF output by passing the embedded
+ text to LaTeX. Some care has to be taken, though, since there are
+ limitations which macros and features can be used in either mode, so
+ it is recommended to always check whether any new or changed
+ documentation does translate and render correctly with either output.
- A test whether all styles are documented and listed in their
respective overview pages. A typical output with warnings looks like this:
@@ -252,6 +251,5 @@ manual with ``make spelling``. This requires `a library called enchant
positives* (e.g. keywords, names, abbreviations) those can be added to
the file ``lammps/doc/utils/sphinx-config/false_positives.txt``.
-.. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html
-
.. _lws: https://www.lammps.org
+.. _rst: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
diff --git a/doc/src/Build_package.rst b/doc/src/Build_package.rst
index 9eeda4d8d4..6d376a7cd6 100644
--- a/doc/src/Build_package.rst
+++ b/doc/src/Build_package.rst
@@ -30,14 +30,16 @@ steps, as explained on the :doc:`Build extras ` page.
These links take you to the extra instructions for those select
packages:
+.. this list must be kept in sync with its counterpart in Build_extras.rst
.. table_from_list::
:columns: 6
* :ref:`ADIOS `
* :ref:`ATC `
* :ref:`AWPMD `
- * :ref:`COLVARS `
+ * :ref:`COLVARS `
* :ref:`COMPRESS `
+ * :ref:`ELECTRODE `
* :ref:`GPU `
* :ref:`H5MD `
* :ref:`INTEL `
@@ -45,7 +47,10 @@ packages:
* :ref:`KOKKOS `
* :ref:`LATTE `
* :ref:`MACHDYN `
+ * :ref:`MDI `
+ * :ref:`MESONT `
* :ref:`ML-HDNNP `
+ * :ref:`ML-IAP `
* :ref:`ML-PACE `
* :ref:`ML-QUIP `
* :ref:`MOLFILE `
diff --git a/doc/src/Build_settings.rst b/doc/src/Build_settings.rst
index 7e627a052f..2d83908bb1 100644
--- a/doc/src/Build_settings.rst
+++ b/doc/src/Build_settings.rst
@@ -111,26 +111,25 @@ LAMMPS can use them if they are available on your system.
files in its default search path. You must specify ``FFT_LIB``
with the appropriate FFT libraries to include in the link.
-The `KISS FFT library `_ 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 a868ad84fc..b0218d4302 100644
--- a/doc/src/Commands_all.rst
+++ b/doc/src/Commands_all.rst
@@ -14,7 +14,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
diff --git a/doc/src/Commands_fix.rst b/doc/src/Commands_fix.rst
index 7dc3f324b4..db9d2a94ee 100644
--- a/doc/src/Commands_fix.rst
+++ b/doc/src/Commands_fix.rst
@@ -40,9 +40,6 @@ OPT.
* :doc:`ave/time `
* :doc:`aveforce `
* :doc:`balance `
- * :doc:`brownian `
- * :doc:`brownian/asphere `
- * :doc:`brownian/sphere `
* :doc:`bocs `
* :doc:`bond/break `
* :doc:`bond/create `
@@ -50,6 +47,9 @@ OPT.
* :doc:`bond/react `
* :doc:`bond/swap `
* :doc:`box/relax `
+ * :doc:`brownian `
+ * :doc:`brownian/asphere `
+ * :doc:`brownian/sphere `
* :doc:`charge/regulation `
* :doc:`cmap `
* :doc:`colvars `
diff --git a/doc/src/Commands_removed.rst b/doc/src/Commands_removed.rst
index 1000d11e29..690921bfc9 100644
--- a/doc/src/Commands_removed.rst
+++ b/doc/src/Commands_removed.rst
@@ -2,14 +2,17 @@ Removed commands and packages
=============================
This page lists LAMMPS commands and packages that have been removed from
-the distribution and provides suggestions for alternatives or replacements.
-LAMMPS has special dummy styles implemented, that will stop LAMMPS and
-print a suitable error message in most cases, when a style/command is used
-that has been removed.
+the distribution and provides suggestions for alternatives or
+replacements. LAMMPS has special dummy styles implemented, that will
+stop LAMMPS and print a suitable error message in most cases, when a
+style/command is used that has been removed or will replace the command
+with the direct alternative (if available) and print a warning.
Fix ave/spatial and fix ave/spatial/sphere
------------------------------------------
+.. deprecated:: 11Dec2015
+
The fixes ave/spatial and ave/spatial/sphere have been removed from LAMMPS
since they were superseded by the more general and extensible "chunk
infrastructure". Here the system is partitioned in one of many possible
@@ -30,18 +33,21 @@ The code in the :ref:`MEAM package ` is a translation of the
Fortran code of MEAM into C++, which removes several restrictions
(e.g. there can be multiple instances in hybrid pair styles) and allows
for some optimizations leading to better performance. The pair style
-:doc:`meam ` has the exact same syntax.
+:doc:`meam ` has the exact same syntax. For a transition
+period the C++ version of MEAM was called USER-MEAMC so it could
+coexist with the Fortran version.
REAX package
------------
The REAX package has been removed since it was superseded by the
-:ref:`REAXFF package `. The REAXFF
-package has been tested to yield equivalent results to the REAX package,
-offers better performance, supports OpenMP multi-threading via OPENMP,
-and GPU and threading parallelization through KOKKOS. The new pair styles
-are not syntax compatible with the removed reax pair style, so input
-files will have to be adapted.
+:ref:`REAXFF package `. The REAXFF package has been tested
+to yield equivalent results to the REAX package, offers better
+performance, supports OpenMP multi-threading via OPENMP, and GPU and
+threading parallelization through KOKKOS. The new pair styles are not
+syntax compatible with the removed reax pair style, so input files will
+have to be adapted. The REAXFF package was originally called
+USER-REAXC.
USER-CUDA package
-----------------
@@ -60,5 +66,6 @@ restart2data tool
The functionality of the restart2data tool has been folded into the
LAMMPS executable directly instead of having a separate tool. A
combination of the commands :doc:`read_restart ` and
-:doc:`write_data ` can be used to the same effect. For added
-convenience this conversion can also be triggered by :doc:`command line flags `
+:doc:`write_data ` can be used to the same effect. For
+added convenience this conversion can also be triggered by
+:doc:`command line flags `
diff --git a/doc/src/Developer.rst b/doc/src/Developer.rst
index bb10fcffd7..dc3fac94ce 100644
--- a/doc/src/Developer.rst
+++ b/doc/src/Developer.rst
@@ -17,6 +17,7 @@ of time and requests from the LAMMPS user community.
Developer_flow
Developer_write
Developer_notes
+ Developer_updating
Developer_plugins
Developer_unittest
Classes
diff --git a/doc/src/Developer_code_design.rst b/doc/src/Developer_code_design.rst
index 820ad47fba..786bd51c26 100644
--- a/doc/src/Developer_code_design.rst
+++ b/doc/src/Developer_code_design.rst
@@ -50,7 +50,7 @@ parallel each MPI process creates such an instance. This can be seen
in the ``main.cpp`` file where the core steps of running a LAMMPS
simulation are the following 3 lines of code:
-.. code-block:: C++
+.. code-block:: c++
LAMMPS *lammps = new LAMMPS(argc, argv, lammps_comm);
lammps->input->file();
@@ -78,7 +78,7 @@ LAMMPS makes extensive use of the object oriented programming (OOP)
principles of *compositing* and *inheritance*. Classes like the
``LAMMPS`` class are a **composite** containing pointers to instances
of other classes like ``Atom``, ``Comm``, ``Force``, ``Neighbor``,
-``Modify``, and so on. Each of these classes implement certain
+``Modify``, and so on. Each of these classes implements certain
functionality by storing and manipulating data related to the
simulation and providing member functions that trigger certain
actions. Some of those classes like ``Force`` are themselves
@@ -87,9 +87,9 @@ interactions. Similarly the ``Modify`` class contains a list of
``Fix`` and ``Compute`` classes. If the input commands that
correspond to these classes include the word *style*, then LAMMPS
stores only a single instance of that class. E.g. *atom_style*,
-*comm_style*, *pair_style*, *bond_style*. It the input command does
-not include the word *style*, there can be many instances of that
-class defined. E.g. *region*, *fix*, *compute*, *dump*.
+*comm_style*, *pair_style*, *bond_style*. If the input command does
+**not** include the word *style*, then there may be many instances of
+that class defined, for example *region*, *fix*, *compute*, *dump*.
**Inheritance** enables creation of *derived* classes that can share
common functionality in their base class while providing a consistent
@@ -232,7 +232,7 @@ macro ``PairStyle()`` will associate the style name "lj/cut"
with a factory function creating an instance of the ``PairLJCut``
class.
-.. code-block:: C++
+.. code-block:: c++
// from force.h
typedef Pair *(*PairCreator)(LAMMPS *);
@@ -360,7 +360,7 @@ characters; "{:<8}" would do this as left aligned, "{:^8}" as centered,
argument type must be compatible or else the {fmt} formatting code will
throw an exception. Some format string examples are given below:
-.. code-block:: C
+.. code-block:: c++
auto mesg = fmt::format(" CPU time: {:4d}:{:02d}:{:02d}\n", cpuh, cpum, cpus);
mesg = fmt::format("{:<8s}| {:<10.5g} | {:<10.5g} | {:<10.5g} |{:6.1f} |{:6.2f}\n",
diff --git a/doc/src/Developer_notes.rst b/doc/src/Developer_notes.rst
index 2b3375265f..a781737d6f 100644
--- a/doc/src/Developer_notes.rst
+++ b/doc/src/Developer_notes.rst
@@ -105,7 +105,7 @@ list, where each pair of atoms is listed only once (except when the
pairs straddling sub-domains or periodic boundaries will be listed twice).
Thus these are the default settings when a neighbor list request is created in:
-.. code-block:: C++
+.. code-block:: c++
void Pair::init_style()
{
@@ -129,7 +129,7 @@ neighbor list request to the specific needs of a style an additional
request flag is needed. The :doc:`tersoff ` pair style,
for example, needs a "full" neighbor list:
-.. code-block:: C++
+.. code-block:: c++
void PairTersoff::init_style()
{
@@ -141,7 +141,7 @@ When a pair style supports r-RESPA time integration with different cutoff region
the request flag may depend on the corresponding r-RESPA settings. Here an example
from pair style lj/cut:
-.. code-block:: C++
+.. code-block:: c++
void PairLJCut::init_style()
{
@@ -160,7 +160,7 @@ Granular pair styles need neighbor lists based on particle sizes and not cutoff
and also may require to have the list of previous neighbors available ("history").
For example with:
-.. code-block:: C++
+.. code-block:: c++
if (use_history) neighbor->add_request(this, NeighConst::REQ_SIZE | NeighConst::REQ_HISTORY);
else neighbor->add_request(this, NeighConst::REQ_SIZE);
@@ -170,7 +170,7 @@ settings each request can set an id which is then used in the corresponding
``init_list()`` function to assign it to the suitable pointer variable. This is
done for example by the :doc:`pair style meam `:
-.. code-block:: C++
+.. code-block:: c++
void PairMEAM::init_style()
{
@@ -189,7 +189,7 @@ just once) and this can also be indicated by a flag. As an example here
is the request from the ``FixPeriNeigh`` class which is created
internally by :doc:`Peridynamics pair styles `:
-.. code-block:: C++
+.. code-block:: c++
neighbor->add_request(this, NeighConst::REQ_FULL | NeighConst::REQ_OCCASIONAL);
@@ -198,7 +198,7 @@ than what is usually inferred from the pair style settings (largest cutoff of
all pair styles plus neighbor list skin). The following is used in the
:doc:`compute rdf ` command implementation:
-.. code-block:: C++
+.. code-block:: c++
if (cutflag)
neighbor->add_request(this, NeighConst::REQ_OCCASIONAL)->set_cutoff(mycutneigh);
@@ -212,7 +212,7 @@ for printing the neighbor list summary the name of the requesting command
should be set. Below is the request from the :doc:`delete atoms `
command:
-.. code-block:: C++
+.. code-block:: c++
neighbor->add_request(this, "delete_atoms", NeighConst::REQ_FULL);
diff --git a/doc/src/Developer_parallel.rst b/doc/src/Developer_parallel.rst
index c7bfcfca9e..f649920dc5 100644
--- a/doc/src/Developer_parallel.rst
+++ b/doc/src/Developer_parallel.rst
@@ -3,9 +3,9 @@ Parallel algorithms
LAMMPS is designed to enable running simulations in parallel using the
MPI parallel communication standard with distributed data via domain
-decomposition. The parallelization aims to be efficient result in good
-strong scaling (= good speedup for the same system) and good weak
-scaling (= the computational cost of enlarging the system is
+decomposition. The parallelization aims to be efficient, and resulting
+in good strong scaling (= good speedup for the same system) and good
+weak scaling (= the computational cost of enlarging the system is
proportional to the system size). Additional parallelization using GPUs
or OpenMP can also be applied within the sub-domain assigned to an MPI
process. For clarity, most of the following illustrations show the 2d
diff --git a/doc/src/Developer_plugins.rst b/doc/src/Developer_plugins.rst
index 36fdd010b3..dd5431507e 100644
--- a/doc/src/Developer_plugins.rst
+++ b/doc/src/Developer_plugins.rst
@@ -95,7 +95,7 @@ a class ``PairMorse2`` in the files ``pair_morse2.h`` and
``pair_morse2.cpp`` with the factory function and initialization
function would look like this:
-.. code-block:: C++
+.. code-block:: c++
#include "lammpsplugin.h"
#include "version.h"
@@ -141,7 +141,7 @@ list of argument strings), then the pointer type is ``lammpsplugin_factory2``
and it must be assigned to the *creator.v2* member of the plugin struct.
Below is an example for that:
-.. code-block:: C++
+.. code-block:: c++
#include "lammpsplugin.h"
#include "version.h"
@@ -176,7 +176,7 @@ demonstrated in the following example, which also shows that the
implementation of the plugin class may be within the same source
file as the plugin interface code:
-.. code-block:: C++
+.. code-block:: c++
#include "lammpsplugin.h"
diff --git a/doc/src/Developer_unittest.rst b/doc/src/Developer_unittest.rst
index 820e911a8f..6bf0e1d7bf 100644
--- a/doc/src/Developer_unittest.rst
+++ b/doc/src/Developer_unittest.rst
@@ -194,7 +194,7 @@ macro. These tests operate by capturing the screen output when executing
the failing command and then comparing that with a provided regular
expression string pattern. Example:
-.. code-block:: C++
+.. code-block:: c++
TEST_F(SimpleCommandsTest, UnknownCommand)
{
@@ -249,7 +249,7 @@ MPI support. These include tests where LAMMPS is run in multi-partition
mode or only on a subset of the MPI world communicator. The CMake
script code for adding this kind of test looks like this:
-.. code-block:: CMake
+.. code-block:: cmake
if (BUILD_MPI)
add_executable(test_library_mpi test_library_mpi.cpp)
@@ -489,7 +489,7 @@ to update the YAML files. Running a command like
.. code-block:: bash
- $ test_pair_style mol-pair-lennard_mdf.yaml -g new.yaml
+ test_pair_style mol-pair-lennard_mdf.yaml -g new.yaml
will read the settings from the ``mol-pair-lennard_mdf.yaml`` file and then compute
the reference data and write a new file with to ``new.yaml``. If this step fails,
@@ -500,13 +500,13 @@ It is also possible to do an update in place with:
.. code-block:: bash
- $ test_pair_style mol-pair-lennard_mdf.yaml -u
+ test_pair_style mol-pair-lennard_mdf.yaml -u
And one can finally run the full set of tests with:
.. code-block:: bash
- $ test_pair_style mol-pair-lennard_mdf.yaml
+ test_pair_style mol-pair-lennard_mdf.yaml
This will just print a summary of the groups of tests. When using the "-v" flag
the test will also keep any LAMMPS output and when using the "-s" flag, there
diff --git a/doc/src/Developer_updating.rst b/doc/src/Developer_updating.rst
new file mode 100644
index 0000000000..c02d6763de
--- /dev/null
+++ b/doc/src/Developer_updating.rst
@@ -0,0 +1,425 @@
+Notes for updating code written for older LAMMPS versions
+---------------------------------------------------------
+
+This section documents how C++ source files that are available *outside
+of the LAMMPS source distribution* (e.g. in external USER packages or as
+source files provided as a supplement to a publication) that are written
+for an older version of LAMMPS and thus need to be updated to be
+compatible with the current version of LAMMPS. Due to the active
+development of LAMMPS it is likely to always be incomplete. Please
+contact developers@lammps.org in case you run across an issue that is not
+(yet) listed here. Please also review the latest information about the
+LAMMPS :doc:`programming style conventions `, especially
+if you are considering to submit the updated version for inclusion into
+the LAMMPS distribution.
+
+Available topics in mostly chronological order are:
+
+- `Setting flags in the constructor`_
+- `Rename of pack/unpack_comm() to pack/unpack_forward_comm()`_
+- `Use ev_init() to initialize variables derived from eflag and vflag`_
+- `Use utils::numeric() functions instead of force->numeric()`_
+- `Use utils::open_potential() function to open potential files`_
+- `Simplify customized error messages`_
+- `Use of "override" instead of "virtual"`_
+- `Simplified and more compact neighbor list requests`_
+- `Split of fix STORE into fix STORE/GLOBAL and fix STORE/PERATOM`_
+- `Use Output::get_dump_by_id() instead of Output::find_dump()`_
+
+----
+
+Setting flags in the constructor
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As LAMMPS gains additional functionality, new flags may need to be set
+in the constructor or a class to signal compatibility with such features.
+Most of the time the defaults are chosen conservatively, but sometimes
+the conservative choice is the uncommon choice, and then those settings
+need to be made when updating code.
+
+Pair styles:
+
+ - ``manybody_flag``: set to 1 if your pair style is not pair-wise additive
+ - ``restartinfo``: set to 0 if your pair style does not store data in restart files
+
+
+Rename of pack/unpack_comm() to pack/unpack_forward_comm()
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionchanged:: 8Aug2014
+
+In this change set the functions to pack data into communication buffers
+and to unpack data from communication buffers for :doc:`forward
+communications ` were renamed from ``pack_comm()``
+and ``unpack_comm()`` to ``pack_forward_comm()`` and
+``unpack_forward_comm()``, respectively. Also the meaning of the return
+value of these functions was changed: rather than returning the number
+of items per atom stored in the buffer, now the total number of items
+added (or unpacked) needs to be returned. Here is an example from the
+`PairEAM` class. Of course the member function declaration in corresponding
+header file needs to be updated accordingly.
+
+Old:
+
+.. code-block:: c++
+
+ int PairEAM::pack_comm(int n, int *list, double *buf, int pbc_flag, int *pbc)
+ {
+ int m = 0;
+ for (int i = 0; i < n; i++) {
+ int j = list[i];
+ buf[m++] = fp[j];
+ }
+ return 1;
+ }
+
+New:
+
+.. code-block:: c++
+
+ int PairEAM::pack_forward_comm(int n, int *list, double *buf, int pbc_flag, int *pbc)
+ {
+ int m = 0;
+ for (int i = 0; i < n; i++) {
+ int j = list[i];
+ buf[m++] = fp[j];
+ }
+ return m;
+ }
+
+.. note::
+
+ Because the various "pack" and "unpack" functions are defined in the
+ respective base classes as dummy functions doing nothing, and because
+ of the the name mismatch the custom versions in the derived class
+ will no longer be called, there will be no compilation error when
+ this change is not applied. Only calculations will suddenly produce
+ incorrect results because the required forward communication calls
+ will cease to function correctly.
+
+Use ev_init() to initialize variables derived from eflag and vflag
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionchanged:: 29Mar2019
+
+There are several variables that need to be initialized based on
+the values of the "eflag" and "vflag" variables and since sometimes
+there are new bits added and new variables need to be set to 1 or 0.
+To make this consistent, across all styles, there is now an inline
+function ``ev_init(eflag, vflag)`` that makes those settings
+consistently and calls either ``ev_setup()`` or ``ev_unset()``.
+Example from a pair style:
+
+Old:
+
+.. code-block:: c++
+
+ if (eflag || vflag) ev_setup(eflag, vflag);
+ else evflag = vflag_fdotr = eflag_global = eflag_atom = 0;
+
+New:
+
+.. code-block:: c++
+
+ ev_init(eflag, vflag);
+
+Not applying this change will not cause a compilation error, but
+can lead to inconsistent behavior and incorrect tallying of
+energy or virial.
+
+Use utils::numeric() functions instead of force->numeric()
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionchanged:: 18Sep2020
+
+The "numeric()" conversion functions (including "inumeric()",
+"bnumeric()", and "tnumeric()") have been moved from the Force class to
+the utils namespace. Also they take an additional argument that selects
+whether the ``Error::all()`` or ``Error::one()`` function should be
+called in case of an error. The former should be used when *all* MPI
+processes call the conversion function and the latter *must* be used
+when they are called from only one or a subset of the MPI processes.
+
+Old:
+
+.. code-block:: c++
+
+ val = force->numeric(FLERR, arg[1]);
+ num = force->inumeric(FLERR, arg[2]);
+
+New:
+
+.. code-block:: c++
+
+ val = utils::numeric(FLERR, true, arg[1], lmp);
+ num = utils::inumeric(FLERR, false, arg[2], lmp);
+
+.. seealso::
+
+ :cpp:func:`utils::numeric() `,
+ :cpp:func:`utils::inumeric() `,
+ :cpp:func:`utils::bnumeric() `,
+ :cpp:func:`utils::tnumeric() `
+
+Use utils::open_potential() function to open potential files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionchanged:: 18Sep2020
+
+The :cpp:func:`utils::open_potential()
+` function must be used to replace
+calls to ``force->open_potential()`` and should be used to replace
+``fopen()`` for opening potential files for reading. The custom
+function does three additional steps compared to ``fopen()``: 1) it will
+try to parse the ``UNITS:`` and ``DATE:`` metadata will stop with an
+error on a units mismatch and will print the date info, if present, in
+the log file; 2) for pair styles that support it, it will set up
+possible automatic unit conversions based on the embedded unit
+information and LAMMPS' current units setting; 3) it will not only try
+to open a potential file at the given path, but will also search in the
+folders listed in the ``LAMMPS_POTENTIALS`` environment variable. This
+allows to keep potential files in a common location instead of having to
+copy them around for simulations.
+
+Old:
+
+.. code-block:: c++
+
+ fp = force->open_potential(filename);
+ fp = fopen(filename, "r");
+
+New:
+
+.. code-block:: c++
+
+ fp = utils::open_potential(filename, lmp);
+
+Simplify customized error messages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionchanged:: 14May2021
+
+Aided by features of the bundled {fmt} library, error messages now
+can have a variable number of arguments and the string will be interpreted
+as a {fmt} style format string so that custom error messages can be
+easily customized without having to use temporary buffers and ``sprintf()``.
+Example:
+
+Old:
+
+.. code-block:: c++
+
+ if (fptr == NULL) {
+ char str[128];
+ sprintf(str,"Cannot open AEAM potential file %s",filename);
+ error->one(FLERR,str);
+ }
+
+New:
+
+.. code-block:: c++
+
+ if (fptr == nullptr)
+ error->one(FLERR, "Cannot open AEAM potential file {}: {}", filename, utils::getsyserror());
+
+Use of "override" instead of "virtual"
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionchanged:: 17Feb2022
+
+Since LAMMPS requires C++11 we switched to use the "override" keyword
+instead of "virtual" to indicate polymorphism in derived classes. This
+allows the C++ compiler to better detect inconsistencies when an
+override is intended or not. Please note that "override" has to be
+added to **all** polymorph functions in derived classes and "virtual"
+*only* to the function in the base class (or the destructor). Here is
+an example from the ``FixWallReflect`` class:
+
+Old:
+
+.. code-block:: c++
+
+ FixWallReflect(class LAMMPS *, int, char **);
+ virtual ~FixWallReflect();
+ int setmask();
+ void init();
+ void post_integrate();
+
+New:
+
+.. code-block:: c++
+
+ FixWallReflect(class LAMMPS *, int, char **);
+ ~FixWallReflect() override;
+ int setmask() override;
+ void init() override;
+ void post_integrate() override;
+
+This change set will neither cause a compilation failure, nor will it
+change functionality, but if you plan to submit the updated code for
+inclusion into the LAMMPS distribution, it will be requested for achieve
+a consistent :doc:`programming style `.
+
+Simplified function names for forward and reverse communication
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionchanged:: 24Mar2022
+
+Rather then using the function name to distinguish between the different
+forward and reverse communication functions for styles, LAMMPS now uses
+the type of the "this" pointer argument.
+
+Old:
+
+.. code-block:: c++
+
+ comm->forward_comm_pair(this);
+ comm->forward_comm_fix(this);
+ comm->forward_comm_compute(this);
+ comm->forward_comm_dump(this);
+ comm->reverse_comm_pair(this);
+ comm->reverse_comm_fix(this);
+ comm->reverse_comm_compute(this);
+ comm->reverse_comm_dump(this);
+
+New:
+
+.. code-block:: c++
+
+ comm->forward_comm(this);
+ comm->reverse_comm(this);
+
+This change is **required** or else the code will not compile.
+
+Simplified and more compact neighbor list requests
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionchanged:: 24Mar2022
+
+This change set reduces the amount of code required to request a
+neighbor list. It enforces consistency and no longer requires to change
+internal data of the request. More information on neighbor list
+requests can be :doc:`found here `. Example from the
+``ComputeRDF`` class:
+
+Old:
+
+.. code-block:: c++
+
+ int irequest = neighbor->request(this,instance_me);
+ neighbor->requests[irequest]->pair = 0;
+ neighbor->requests[irequest]->compute = 1;
+ neighbor->requests[irequest]->occasional = 1;
+ if (cutflag) {
+ neighbor->requests[irequest]->cut = 1;
+ neighbor->requests[irequest]->cutoff = mycutneigh;
+ }
+
+New:
+
+.. code-block:: c++
+
+ auto req = neighbor->add_request(this, NeighConst::REQ_OCCASIONAL);
+ if (cutflag) req->set_cutoff(mycutneigh);
+
+Public access to the ``NeighRequest`` class data members has been
+removed so this update is **required** to avoid compilation failure.
+
+Split of fix STORE into fix STORE/GLOBAL and fix STORE/PERATOM
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. 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
+shared code between the two fix STORE modes and the two different code
+paths had to be prefixed with if statements. Furthermore, some flags
+were used differently in the two modes leading to confusion. Splitting
+the code into two fix styles, makes it more easily maintainable. Since
+these are internal fixes, there is no user visible change.
+
+Old:
+
+.. code-block:: c++
+
+ #include "fix_store.h"
+
+ FixStore *fix = dynamic_cast(
+ modify->add_fix(fmt::format("{} {} STORE peratom 1 13",id_pole,group->names[0]));
+
+ FixStore *fix = dynamic_cast(modify->get_fix_by_id(id_pole));
+
+New:
+
+.. code-block:: c++
+
+ #include "fix_store_peratom.h"
+
+ FixStorePeratom *fix = dynamic_cast(
+ modify->add_fix(fmt::format("{} {} STORE/PERATOM 1 13",id_pole,group->names[0]));
+
+ FixStorePeratom *fix = dynamic_cast(modify->get_fix_by_id(id_pole));
+
+Old:
+
+.. code-block:: c++
+
+ #include "fix_store.h"
+
+ FixStore *fix = dynamic_cast(
+ modify->add_fix(fmt::format("{} {} STORE global 1 1",id_fix,group->names[igroup]));
+
+ FixStore *fix = dynamic_cast(modify->get_fix_by_id(id_fix));
+
+New:
+
+.. code-block:: c++
+
+ #include "fix_store_global.h"
+
+ FixStoreGlobal *fix = dynamic_cast(
+ modify->add_fix(fmt::format("{} {} STORE/GLOBAL 1 1",id_fix,group->names[igroup]));
+
+ FixStoreGlobal *fix = dynamic_cast(modify->get_fix_by_id(id_fix));
+
+This change is **required** or else the code will not compile.
+
+Use Output::get_dump_by_id() instead of Output::find_dump()
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. 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
+the list of dumps to ``Output::get_dump_by_id()`` returning a pointer to
+the dump directly. Example:
+
+Old:
+
+.. code-block:: c++
+
+ int idump = output->find_dump(arg[iarg+1]);
+ if (idump < 0)
+ error->all(FLERR,"Dump ID in hyper command does not exist");
+ memory->grow(dumplist,ndump+1,"hyper:dumplist");
+ dumplist[ndump++] = idump;
+
+ [...]
+
+ if (dumpflag)
+ for (int idump = 0; idump < ndump; idump++)
+ output->dump[dumplist[idump]]->write();
+
+New:
+
+.. code-block:: c++
+
+ auto idump = output->get_dump_by_id(arg[iarg+1]);
+ if (!idump) error->all(FLERR,"Dump ID {} in hyper command does not exist", arg[iarg+1]);
+ dumplist.emplace_back(idump);
+
+ [...]
+
+ if (dumpflag) for (auto idump : dumplist) idump->write();
+
+This change is **required** or else the code will not compile.
diff --git a/doc/src/Developer_utils.rst b/doc/src/Developer_utils.rst
index 2b044272fe..212e58384c 100644
--- a/doc/src/Developer_utils.rst
+++ b/doc/src/Developer_utils.rst
@@ -305,7 +305,7 @@ are all "whitespace" characters, i.e. the space character, the tabulator
character, the carriage return character, the linefeed character, and
the form feed character.
-.. code-block:: C++
+.. code-block:: c++
:caption: Tokenizer class example listing entries of the PATH environment variable
#include "tokenizer.h"
@@ -337,7 +337,7 @@ tokenizer into a ``try`` / ``catch`` block to handle errors. The
when a (type of) number is requested as next token that is not
compatible with the string representing the next word.
-.. code-block:: C++
+.. code-block:: c++
:caption: ValueTokenizer class example with exception handling
#include "tokenizer.h"
@@ -415,7 +415,7 @@ one or two array indices "[]" with numbers > 0.
A typical code segment would look like this:
-.. code-block:: C++
+.. code-block:: c++
:caption: Usage example for ArgInfo class
int nvalues = 0;
@@ -464,7 +464,7 @@ open the file, and will call the :cpp:class:`LAMMPS_NS::Error` class in
case of failures to read or to convert numbers, so that LAMMPS will be
aborted.
-.. code-block:: C++
+.. code-block:: c++
:caption: Use of PotentialFileReader class in pair style coul/streitz
PotentialFileReader reader(lmp, file, "coul/streitz");
@@ -543,7 +543,7 @@ chunk size needs to be known in advance, 2) with :cpp:func:`MyPage::vget()
its size is registered later with :cpp:func:`MyPage::vgot()
`.
-.. code-block:: C++
+.. code-block:: c++
:caption: Example of using :cpp:class:`MyPage `
#include "my_page.h"
diff --git a/doc/src/Developer_write.rst b/doc/src/Developer_write.rst
index bdc6559060..c374ec2e77 100644
--- a/doc/src/Developer_write.rst
+++ b/doc/src/Developer_write.rst
@@ -26,7 +26,7 @@ constructor with the signature: ``FixPrintVel(class LAMMPS *, int, char **)``.
Every fix must be registered in LAMMPS by writing the following lines
of code in the header before include guards:
-.. code-block:: c
+.. code-block:: c++
#ifdef FIX_CLASS
// clang-format off
@@ -47,7 +47,7 @@ keyword when it parses the input script.
Let's write a simple fix which will print the average velocity at the end
of each timestep. First of all, implement a constructor:
-.. code-block:: C++
+.. code-block:: c++
FixPrintVel::FixPrintVel(LAMMPS *lmp, int narg, char **arg)
: Fix(lmp, narg, arg)
@@ -72,7 +72,7 @@ in the Fix class called ``nevery`` which specifies how often the method
The next method we need to implement is ``setmask()``:
-.. code-block:: C++
+.. code-block:: c++
int FixPrintVel::setmask()
{
@@ -87,7 +87,7 @@ during execution. The constant ``END_OF_STEP`` corresponds to the
are called during a timestep and the order in which they are called
are shown in the previous section.
-.. code-block:: C++
+.. code-block:: c++
void FixPrintVel::end_of_step()
{
@@ -143,7 +143,7 @@ The group membership information of an atom is contained in the *mask*
property of and atom and the bit corresponding to a given group is
stored in the groupbit variable which is defined in Fix base class:
-.. code-block:: C++
+.. code-block:: c++
for (int i = 0; i < nlocal; ++i) {
if (atom->mask[i] & groupbit) {
@@ -174,7 +174,7 @@ to store positions of atoms from previous timestep, we need to add
``double** xold`` to the header file. Than add allocation code
to the constructor:
-.. code-block:: C++
+.. code-block:: c++
FixSavePos::FixSavePos(LAMMPS *lmp, int narg, char **arg), xold(nullptr)
{
@@ -190,7 +190,7 @@ to the constructor:
Implement the aforementioned methods:
-.. code-block:: C++
+.. code-block:: c++
double FixSavePos::memory_usage()
{
diff --git a/doc/src/Errors_debug.rst b/doc/src/Errors_debug.rst
index 786a21ecae..ad0e5404e5 100644
--- a/doc/src/Errors_debug.rst
+++ b/doc/src/Errors_debug.rst
@@ -40,7 +40,7 @@ We use it to show how to identify the origin of a segmentation fault.
After recompiling LAMMPS and running the input you should get something like this:
-.. code-block::
+.. code-block:: console
$ ./lmp -in in.melt
LAMMPS (19 Mar 2020)
@@ -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 `_.
+documentation `_.
Run LAMMPS from within the debugger
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -90,8 +90,9 @@ it. When it reaches the code causing the segmentation fault, it will
stop with a message why it stopped, print the current line of code, and
drop back to the GDB prompt.
-.. code-block::
+.. code-block:: console
+ (gdb) run
[...]
Setting up Verlet run ...
Unit style : lj
@@ -106,7 +107,7 @@ drop back to the GDB prompt.
Now typing the command "where" will show the stack of functions starting from
the current function back to "main()".
-.. code-block::
+.. code-block:: console
(gdb) where
#0 0x00000000006653ab in LAMMPS_NS::PairLJCut::compute (this=0x829740, eflag=1, vflag=) at /home/akohlmey/compile/lammps/src/pair_lj_cut.cpp:139
@@ -124,7 +125,7 @@ You can also print the value of variables and see if there is anything
unexpected. Segmentation faults, for example, commonly happen when a
pointer variable is not assigned and still initialized to NULL.
-.. code-block::
+.. code-block:: console
(gdb) print x
$1 = (double **) 0x7ffff7ca1010
@@ -153,7 +154,7 @@ utility to the current folder. Example: ``coredumpctl -o core dump lmp``.
Now you can launch the debugger to load the executable, its debug info
and the core dump and drop you to a prompt like before.
-.. code-block::
+.. code-block:: console
$ gdb lmp core
Reading symbols from lmp...
@@ -186,7 +187,7 @@ recommended to redirect the valgrind output to a file (e.g. with
process ID) so that the messages of the multiple valgrind instances to
the console are not mixed.
-.. code-block::
+.. code-block:: console
$ valgrind ./lmp -in in.melt
==1933642== Memcheck, a memory error detector
diff --git a/doc/src/Fortran.rst b/doc/src/Fortran.rst
index fef2ec8def..8b80052366 100644
--- a/doc/src/Fortran.rst
+++ b/doc/src/Fortran.rst
@@ -1,32 +1,51 @@
-The ``LIBLAMMPS`` Fortran Module
-********************************
+The :f:mod:`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.
+The :f:mod:`LIBLAMMPS` module provides an interface to call LAMMPS from
+Fortran. It is based on the LAMMPS C library interface and requires a
+fully 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 other than those in the C library interface and the
+LAMMPS Fortran module itself.
While C libraries have a defined binary interface (ABI) and can thus be
-used from multiple compiler versions from different vendors for as long
-as they are compatible with the hosting operating system, the same is
-not true for Fortran codes. Thus the LAMMPS Fortran module needs to be
+used from multiple compiler versions from different vendors as long as
+they are compatible with the hosting operating system, the same is not
+true for Fortran programs. Thus, the LAMMPS Fortran module needs to be
compiled alongside the code using it from the source code in
-``fortran/lammps.f90``. When linking, you also need to
-:doc:`link to the LAMMPS library `. A typical command line
-for a simple program using the Fortran interface would be:
+``fortran/lammps.f90`` *and* with the same compiler used to build the
+rest of the Fortran code that interfaces to LAMMPS. When linking, you
+also need to :doc:`link to the LAMMPS library `. A typical
+command line for a simple program using the Fortran interface would be:
.. code-block:: bash
- mpifort -o testlib.x lammps.f90 testlib.f90 -L. -llammps
+ 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.
+Please note that the MPI compiler wrapper is only required when the
+calling the library *from* an MPI-parallelized program. Otherwise,
+using the plain Fortran compiler (gfortran, ifort, flang, etc.) will
+suffice, since there are no direct references to MPI library features,
+definitions and subroutine calls; MPI communicators are referred to by
+their integer index representation as required by the Fortran MPI
+interface. 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 dynamic library `.
-.. versionadded:: 9Oct2020
+If the LAMMPS library itself has been compiled with MPI support, the
+resulting executable will be able to run LAMMPS in parallel with
+``mpirun``, ``mpiexec``, or equivalent. This may be either on the
+"world" communicator or a sub-communicator created by the calling
+Fortran code. If, on the other hand, the LAMMPS library has been
+compiled **without** MPI support, each LAMMPS instance will run
+independently using just one processor.
+
+Please also note that the order of the source files matters: the
+``lammps.f90`` file needs to be compiled first, since it provides the
+:f:mod:`LIBLAMMPS` module that would need to be imported by the calling
+Fortran code in order to uses the Fortran interface.
+A working example can be found together with equivalent examples in C and
+C++ in the ``examples/COUPLE/simple`` folder of the LAMMPS distribution.
.. admonition:: Work in Progress
:class: note
@@ -49,61 +68,96 @@ 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
-LIBLAMMPS`` statement. Internally it will call either
+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:
+optional and :cpp:func:`lammps_mpi_init` will be called automatically
+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
PROGRAM testlib
USE LIBLAMMPS ! include the LAMMPS library interface
- TYPE(lammps) :: lmp ! derived type to hold LAMMPS instance
- CHARACTER(len=*), DIMENSION(*), PARAMETER :: args = &
- [ CHARACTER(len=12) :: 'liblammps', '-log', 'none' ]
+ IMPLICIT NONE
+ TYPE(lammps) :: lmp ! derived type to hold LAMMPS instance
+ CHARACTER(LEN=12), PARAMETER :: args(3) = &
+ [ CHARACTER(LEN=12) :: 'liblammps', '-log', 'none' ]
! create a LAMMPS instance (and initialize MPI)
lmp = lammps(args)
! get and print numerical version code
PRINT*, 'LAMMPS Version: ', lmp%version()
- ! delete LAMMPS instance (and shuts down MPI)
- CALL lmp%close(.true.)
-
+ ! delete LAMMPS instance (and shutdown MPI)
+ CALL lmp%close(.TRUE.)
END PROGRAM testlib
+It is also possible to pass command line flags from Fortran to C/C++ and
+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
+version of the previous example:
+
+.. code-block:: fortran
+
+ PROGRAM testlib2
+ USE LIBLAMMPS ! include the LAMMPS library interface
+ IMPLICIT NONE
+ TYPE(lammps) :: lmp ! derived type to hold LAMMPS instance
+ CHARACTER(LEN=128), ALLOCATABLE :: command_args(:)
+ INTEGER :: i, argc
+
+ ! copy command line flags to `command_args()`
+ argc = COMMAND_ARGUMENT_COUNT()
+ ALLOCATE(command_args(0:argc))
+ DO i=0, argc
+ CALL GET_COMMAND_ARGUMENT(i, command_args(i))
+ END DO
+
+ ! create a LAMMPS instance (and initialize MPI)
+ lmp = lammps(command_args)
+ ! get and print numerical version code
+ PRINT*, 'Program name: ', command_args(0)
+ PRINT*, 'LAMMPS Version: ', lmp%version()
+ ! delete LAMMPS instance (and shuts down MPI)
+ CALL lmp%close(.TRUE.)
+ DEALLOCATE(command_args)
+ END PROGRAM testlib2
+
--------------------
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
-C-library interface, the corresponding Fortran versions of the calls
+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
+:f:func:`commands_string`) have to make copies of the strings passed as
arguments so that they can be modified to be compatible with the
requirements of strings in C without affecting the original strings.
Those copies are automatically deleted after the functions return.
-Below is a small demonstration of the uses of the different functions:
+Below is a small demonstration of the uses of the different functions.
.. code-block:: fortran
PROGRAM testcmd
USE LIBLAMMPS
- TYPE(lammps) :: lmp
- CHARACTER(len=512) :: cmds
- CHARACTER(len=40),ALLOCATABLE :: cmdlist(:)
- CHARACTER(len=10) :: trimmed
+ TYPE(lammps) :: lmp
+ CHARACTER(LEN=512) :: cmds
+ CHARACTER(LEN=40), ALLOCATABLE :: cmdlist(:)
+ CHARACTER(LEN=10) :: trimmed
INTEGER :: i
lmp = lammps()
@@ -111,10 +165,10 @@ Below is a small demonstration of the uses of the different functions:
CALL lmp%command('variable zpos index 1.0')
! define 10 groups of 10 atoms each
ALLOCATE(cmdlist(10))
- DO i=1,10
- WRITE(trimmed,'(I10)') 10*i
- WRITE(cmdlist(i),'(A,I1,A,I10,A,A)') &
- 'group g',i-1,' id ',10*(i-1)+1,':',ADJUSTL(trimmed)
+ DO i=1, 10
+ WRITE(trimmed,'(I10)') 10*i
+ WRITE(cmdlist(i),'(A,I1,A,I10,A,A)') &
+ 'group g', i-1, ' id ', 10*(i-1)+1, ':', ADJUSTL(trimmed)
END DO
CALL lmp%commands_list(cmdlist)
! run multiple commands from multi-line string
@@ -123,8 +177,7 @@ Below is a small demonstration of the uses of the different functions:
'create_box 1 box' // NEW_LINE('A') // &
'create_atoms 1 single 1.0 1.0 ${zpos}'
CALL lmp%commands_string(cmds)
- CALL lmp%close()
-
+ CALL lmp%close(.TRUE.)
END PROGRAM testcmd
---------------
diff --git a/doc/src/Howto.rst b/doc/src/Howto.rst
index 0f1abcd7d7..3afbd93b4f 100644
--- a/doc/src/Howto.rst
+++ b/doc/src/Howto.rst
@@ -83,6 +83,7 @@ Packages howto
Howto_coreshell
Howto_drude
Howto_drude2
+ Howto_peri
Howto_manifold
Howto_spins
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_cmake.rst b/doc/src/Howto_cmake.rst
index 832a8b8770..8ac957f554 100644
--- a/doc/src/Howto_cmake.rst
+++ b/doc/src/Howto_cmake.rst
@@ -46,7 +46,7 @@ This tutorial assumes that you are operating in a command-line environment
using a shell like Bash.
- Linux: any Terminal window will work
-- MacOS X: launch the Terminal application.
+- macOS: launch the Terminal application.
- Windows 10: install and run the :doc:`Windows Subsystem for Linux `
We also assume that you have downloaded and unpacked a recent LAMMPS source code package
@@ -56,7 +56,7 @@ You should change into the top level directory of the LAMMPS source tree all
paths mentioned in the tutorial are relative to that. Immediately after downloading
it should look like this:
-.. code-block:: bash
+.. code-block:: console
$ ls
bench doc lib potentials README tools
@@ -104,7 +104,7 @@ the progress of the configuration printed to the screen followed by a
summary of the enabled features, options and compiler settings. A typical
summary screen will look like this:
-.. code-block::
+.. code-block:: console
$ cmake ../cmake/
-- The CXX compiler identification is GNU 8.2.0
diff --git a/doc/src/Howto_github.rst b/doc/src/Howto_github.rst
index 315bacac69..ab7723e8fb 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
-`_ to familiarize yourself with some of the
+`_ to familiarize yourself with some of the
more advanced git features used below.
As of fall 2016, submitting contributions to LAMMPS via pull requests
@@ -78,13 +78,13 @@ machine via HTTPS:
.. code-block:: bash
- $ git clone https://github.com//lammps.git
+ git clone https://github.com//lammps.git
or, if you have set up your GitHub account for using SSH keys, via SSH:
.. code-block:: bash
- $ git clone git@github.com:/lammps.git
+ git clone git@github.com:/lammps.git
You can find the proper URL by clicking the "Clone or download"-button:
@@ -103,21 +103,21 @@ and use git pull:
.. code-block:: bash
- $ cd mylammps
- $ git checkout develop
- $ git pull https://github.com/lammps/lammps develop
+ cd mylammps
+ git checkout develop
+ git pull https://github.com/lammps/lammps develop
You can also add this URL as a remote:
.. code-block:: bash
- $ git remote add upstream https://www.github.com/lammps/lammps
+ git remote add upstream https://www.github.com/lammps/lammps
From then on you can update your upstream branches with:
.. code-block:: bash
- $ git fetch upstream
+ git fetch upstream
and then refer to the upstream repository branches with
`upstream/develop` or `upstream/release` and so on.
@@ -129,8 +129,8 @@ workflow that updated this tutorial, and hence we will call the branch
.. code-block:: bash
- $ git fetch upstream
- $ git checkout -b github-tutorial-update upstream/develop
+ git fetch upstream
+ git checkout -b github-tutorial-update upstream/develop
Now that we have changed branches, we can make our changes to our local
repository. Just remember that if you want to start working on another,
@@ -150,8 +150,8 @@ After everything is done, add the files to the branch and commit them:
.. code-block:: bash
- $ git add doc/src/Howto_github.txt
- $ git add doc/src/JPG/tutorial*.png
+ git add doc/src/Howto_github.txt
+ git add doc/src/JPG/tutorial*.png
.. warning::
@@ -174,13 +174,13 @@ useful message that explains the change.
.. code-block:: bash
- $ git commit -m 'Finally updated the GitHub tutorial'
+ git commit -m 'Finally updated the GitHub tutorial'
After the commit, the changes can be pushed to the same branch on GitHub:
.. code-block:: bash
- $ git push
+ git push
Git will ask you for your user name and password on GitHub if you have
not configured anything. If your local branch is not present on GitHub yet,
@@ -188,7 +188,7 @@ it will ask you to add it by running
.. code-block:: bash
- $ git push --set-upstream origin github-tutorial-update
+ git push --set-upstream origin github-tutorial-update
If you correctly type your user name and
password, the feature branch should be added to your fork on GitHub.
@@ -198,13 +198,13 @@ If you want to make really sure you push to the right repository
.. code-block:: bash
- $ git push origin
+ git push origin
or using an explicit URL:
.. code-block:: bash
- $ git push git@github.com:Pakketeretet2/lammps.git
+ git push git@github.com:Pakketeretet2/lammps.git
----------
@@ -412,10 +412,10 @@ we need to pull Axel's change back into our branch, and merge them:
.. code-block:: bash
- $ git add Howto_github.txt
- $ git add JPG/tutorial_reverse_pull_request*.png
- $ git commit -m "Updated text and images on reverse pull requests"
- $ git pull
+ git add Howto_github.txt
+ git add JPG/tutorial_reverse_pull_request*.png
+ git commit -m "Updated text and images on reverse pull requests"
+ git pull
In this case, the merge was painless because git could auto-merge:
@@ -428,10 +428,10 @@ commit and push again:
.. code-block:: bash
- $ git add Howto_github.txt
- $ git add JPG/tutorial_reverse_pull_request6.png
- $ git commit -m "Merged Axel's suggestions and updated text"
- $ git push git@github.com:Pakketeretet2/lammps
+ git add Howto_github.txt
+ git add JPG/tutorial_reverse_pull_request6.png
+ git commit -m "Merged Axel's suggestions and updated text"
+ git push git@github.com:Pakketeretet2/lammps
This merge also shows up on the lammps GitHub page:
@@ -456,9 +456,9 @@ branch!
.. code-block:: bash
- $ git checkout develop
- $ git pull https://github.com/lammps/lammps develop
- $ git branch -d github-tutorial-update
+ git checkout develop
+ git pull https://github.com/lammps/lammps develop
+ git branch -d github-tutorial-update
If you do not pull first, it is not really a problem but git will warn
you at the next statement that you are deleting a local branch that
@@ -472,7 +472,7 @@ to your remote(s) as well:
.. code-block:: bash
- $ git push origin :github-tutorial-update
+ git push origin :github-tutorial-update
**Recent changes in the workflow**
@@ -486,5 +486,6 @@ simplify comparisons between releases. Finally, all patches and
submissions are subject to automatic testing and code checks to make
sure they at the very least compile.
-A discussion of the LAMMPS developer GitHub workflow can be found in the file
-`doc/github-development-workflow.md `_
+A discussion of the LAMMPS developer GitHub workflow can be found in the
+file `doc/github-development-workflow.md
+`_
diff --git a/doc/src/Howto_manifold.rst b/doc/src/Howto_manifold.rst
index 8c2cbadc42..67c9d70ea6 100644
--- a/doc/src/Howto_manifold.rst
+++ b/doc/src/Howto_manifold.rst
@@ -47,4 +47,4 @@ to the relevant fixes.
.. _Paquay1:
**(Paquay)** Paquay and Kusters, Biophys. J., 110, 6, (2016).
-preprint available at `arXiv:1411.3019 `_.
+preprint available at `arXiv:1411.3019 `_.
diff --git a/doc/src/Howto_output.rst b/doc/src/Howto_output.rst
index d17b865bbd..42523f434c 100644
--- a/doc/src/Howto_output.rst
+++ b/doc/src/Howto_output.rst
@@ -22,10 +22,11 @@ commands you specify.
As discussed below, LAMMPS gives you a variety of ways to determine
what quantities are computed and printed when the thermodynamics,
dump, or fix commands listed above perform output. Throughout this
-discussion, note that users can also :doc:`add their own computes and fixes to LAMMPS ` which can then generate values that can then be
-output with these commands.
+discussion, note that users can also :doc:`add their own computes and
+fixes to LAMMPS ` which can then generate values that can then
+be output with these commands.
-The following sub-sections discuss different LAMMPS command related
+The following sub-sections discuss different LAMMPS commands related
to output and the kind of data they operate on and produce:
* :ref:`Global/per-atom/local data `
@@ -94,11 +95,11 @@ script references the data determines which style is meant. Example: if
a compute provides both a global scalar and a per-atom vector, the
former will be accessed by using ``c_ID`` in an equal-style variable,
while the latter will be accessed by using ``c_ID`` in an atom-style
-variable. Note that atom-style variable formulas can also access global
-scalars, but in this case it is not possible to do directly because of
-the ambiguity. Instead, an equal-style variable can be defined which
-accesses the global scalar, and that variable used in the atom-style
-variable formula in place of ``c_ID``.
+variable. Note that atom-style variable formulas can also access
+global scalars, but in this case it is not possible to do this
+directly because of the ambiguity. Instead, an equal-style variable
+can be defined which accesses the global scalar, and that variable can
+be used in the atom-style variable formula in place of ``c_ID``.
.. _thermo:
@@ -141,9 +142,10 @@ There is also a :doc:`dump custom ` format where the user
specifies what values are output with each atom. Pre-defined atom
attributes can be specified (id, x, fx, etc). Three additional kinds
of keywords can also be specified (c_ID, f_ID, v_name), where a
-:doc:`compute ` or :doc:`fix ` or :doc:`variable `
-provides the values to be output. In each case, the compute, fix, or
-variable must generate per-atom values for input to the :doc:`dump custom ` command.
+:doc:`compute ` or :doc:`fix ` or :doc:`variable
+` provides the values to be output. In each case, the
+compute, fix, or variable must generate per-atom values for input to
+the :doc:`dump custom ` command.
There is also a :doc:`dump local ` format where the user specifies
what local values to output. A pre-defined index keyword can be
@@ -160,12 +162,13 @@ Fixes that write output files
-----------------------------
Several fixes take various quantities as input and can write output
-files: :doc:`fix ave/time `, :doc:`fix ave/chunk `, :doc:`fix ave/histo `,
-:doc:`fix ave/correlate `, and :doc:`fix print `.
+files: :doc:`fix ave/time `, :doc:`fix ave/chunk
+`, :doc:`fix ave/histo `, :doc:`fix
+ave/correlate `, and :doc:`fix print `.
-The :doc:`fix ave/time ` command enables direct output to
-a file and/or time-averaging of global scalars or vectors. The user
-specifies one or more quantities as input. These can be global
+The :doc:`fix ave/time ` command enables direct output
+to a file and/or time-averaging of global scalars or vectors. The
+user specifies one or more quantities as input. These can be global
:doc:`compute ` values, global :doc:`fix ` values, or
:doc:`variables ` of any style except the atom style which
produces per-atom values. Since a variable can refer to keywords used
@@ -184,8 +187,8 @@ atoms, e.g. individual molecules. The per-atom quantities can be atom
density (mass or number) or atom attributes such as position,
velocity, force. They can also be per-atom quantities calculated by a
:doc:`compute `, by a :doc:`fix `, or by an atom-style
-:doc:`variable `. The chunk-averaged output of this fix can
-also be used as input to other output commands.
+:doc:`variable `. The chunk-averaged output of this fix is
+global and can also be used as input to other output commands.
The :doc:`fix ave/histo ` command enables direct output
to a file of histogrammed quantities, which can be global or per-atom
@@ -202,32 +205,35 @@ written to the screen and log file or to a separate file, periodically
during a running simulation. The line can contain one or more
:doc:`variable ` values for any style variable except the
vector or atom styles). As explained above, variables themselves can
-contain references to global values generated by :doc:`thermodynamic keywords `, :doc:`computes `,
-:doc:`fixes `, or other :doc:`variables `, or to per-atom
-values for a specific atom. Thus the :doc:`fix print `
-command is a means to output a wide variety of quantities separate
-from normal thermodynamic or dump file output.
+contain references to global values generated by :doc:`thermodynamic
+keywords `, :doc:`computes `, :doc:`fixes
+`, or other :doc:`variables `, or to per-atom values
+for a specific atom. Thus the :doc:`fix print ` command is
+a means to output a wide variety of quantities separate from normal
+thermodynamic or dump file output.
.. _computeoutput:
Computes that process output quantities
---------------------------------------
-The :doc:`compute reduce ` and :doc:`compute reduce/region ` commands take one or more per-atom
-or local vector quantities as inputs and "reduce" them (sum, min, max,
+The :doc:`compute reduce ` and :doc:`compute
+reduce/region ` commands take one or more per-atom or
+local vector quantities as inputs and "reduce" them (sum, min, max,
ave) to scalar quantities. These are produced as output values which
can be used as input to other output commands.
-The :doc:`compute slice ` command take one or more global
-vector or array quantities as inputs and extracts a subset of their
-values to create a new vector or array. These are produced as output
-values which can be used as input to other output commands.
+The :doc:`compute slice ` command take one or more
+global vector or array quantities as inputs and extracts a subset of
+their values to create a new vector or array. These are produced as
+output values which can be used as input to other output commands.
-The :doc:`compute property/atom ` command takes a
-list of one or more pre-defined atom attributes (id, x, fx, etc) and
+The :doc:`compute property/atom ` command takes
+a list of one or more pre-defined atom attributes (id, x, fx, etc) and
stores the values in a per-atom vector or array. These are produced
as output values which can be used as input to other output commands.
-The list of atom attributes is the same as for the :doc:`dump custom ` command.
+The list of atom attributes is the same as for the :doc:`dump custom
+` command.
The :doc:`compute property/local ` command takes
a list of one or more pre-defined local attributes (bond info, angle
diff --git a/doc/src/Howto_peri.rst b/doc/src/Howto_peri.rst
new file mode 100644
index 0000000000..4c78d04833
--- /dev/null
+++ b/doc/src/Howto_peri.rst
@@ -0,0 +1,1078 @@
+Peridynamics with LAMMPS
+========================
+
+This Howto is based on the Sandia report 2010-5549 by Michael L. Parks,
+Pablo Seleson, Steven J. Plimpton, Richard B. Lehoucq, and
+Stewart A. Silling.
+
+Overview
+""""""""
+
+Peridynamics is a nonlocal extension of classical continuum mechanics.
+The discrete peridynamic model has the same computational structure as a
+molecular dynamics model. This Howto provides a brief overview of the
+peridynamic model of a continuum, then discusses how the peridynamic
+model is discretized within LAMMPS as described in the original article
+:ref:`(Parks) `. An example problem with comments is also
+included.
+
+Quick Start
+"""""""""""
+
+The peridynamics styles are included in the optional :ref:`PERI package
+`. If your LAMMPS executable does not already include the
+PERI package, you can see the :doc:`build instructions for packages
+` for how to enable the package when compiling a custom
+version of LAMMPS from source.
+
+Here is a minimal example for setting up a peridynamics simulation.
+
+.. code-block:: LAMMPS
+
+ units si
+ boundary s s s
+ lattice sc 0.0005
+ atom_style peri
+ atom_modify map array
+ neighbor 0.0010 bin
+ region target cylinder y 0.0 0.0 0.0050 -0.0050 0.0 units box
+ create_box 1 target
+ create_atoms 1 region target
+
+ pair_style peri/pmb
+ pair_coeff * * 1.6863e22 0.0015001 0.0005 0.25
+ set group all density 2200
+ set group all volume 1.25e-10
+ velocity all set 0.0 0.0 0.0 sum no units box
+ fix 1 all nve
+ compute 1 all damage/atom
+ timestep 1.0e-7
+
+Some notes on this input example:
+
+- peridynamics simulations typically use SI :doc:`units `
+- particles must be created on a :doc:`simple cubic lattice `
+- using the :doc:`atom style peri ` is required
+- an :doc:`atom map ` is required for indexing particles
+- The :doc:`skin distance ` used when computing neighbor lists
+ should be defined appropriately for your choice of simulation
+ parameters. The *skin* should be set to a value such that the
+ peridynamic horizon plus the skin distance is larger than the maximum
+ possible distance between two bonded particles (before their bond
+ breaks). Here it is set to 0.001 meters.
+- a :doc:`peridynamics pair style ` is required. Available
+ choices are currently: *peri/eps*, *peri/lps*, *peri/pmb*, and
+ *peri/ves*. The model parameters are set with a :doc:`pair_coeff
+ ` command.
+- the mass density and volume fraction for each particle must be
+ defined. This is done with the two :doc:`set ` commands for
+ *density* and *volume*. For a simple cubic lattice, the volume of a
+ particle should be equal to the cube of the lattice constant, here
+ :math:`V_i = \Delta x ^3`.
+- with the :doc:`velocity ` command all particles are initially at rest
+- a plain :doc:`velocity-Verlet time integrator ` is used,
+ which is algebraically equivalent to a centered difference in time,
+ but numerically more stable
+- you can compute the damage at the location of each particle with
+ :doc:`compute damage/atom `
+- finally, the timestep is set to 0.1 microseconds with the
+ :doc:`timestep ` command.
+
+
+Peridynamic Model of a Continuum
+""""""""""""""""""""""""""""""""
+
+The following is not a complete overview of peridynamics, but a
+discussion of only those details specific to the model we have
+implemented within LAMMPS. For more on the peridynamic theory, the
+reader is referred to :ref:`(Silling 2007) `. To begin,
+we define the notation we will use.
+
+Basic Notation
+^^^^^^^^^^^^^^
+
+Within the peridynamic literature, the following notational conventions
+are generally used. The position of a given point in the reference
+configuration is :math:`\textbf{x}`. Let
+:math:`\mathbf{u}(\mathbf{x},t)` and :math:`\mathbf{y}(\mathbf{x},t)`
+denote the displacement and position, respectively, of the point
+:math:`\mathbf{x}` at time :math:`t`. Define the relative position and
+displacement vectors of two bonded points :math:`\textbf{x}` and
+:math:`\textbf{x}^\prime` as :math:`\mathbf{\xi} = \textbf{x}^\prime -
+\textbf{x}` and :math:`\mathbf{\eta} = \textbf{u}(\textbf{x}^\prime,t) -
+\textbf{u}(\textbf{x},t)`, respectively. We note here that
+:math:`\mathbf{\eta}` is time-dependent, and that :math:`\mathbf{\xi}`
+is not. It follows that the relative position of the two bonded points
+in the current configuration can be written as :math:`\boldsymbol{\xi} +
+\boldsymbol{\eta} =
+\mathbf{y}(\mathbf{x}^{\prime},t)-\mathbf{y}(\mathbf{x},t)`.
+
+Peridynamic models are frequently written using *states*, which we
+briefly describe here. For the purposes of our discussion, all states
+are operators that act on vectors in :math:`\mathbb{R}^3`. For a more
+complete discussion of states, see :ref:`(Silling 2007)
+`. A *vector state* is an operator whose image is a
+vector, and may be viewed as a generalization of a second-rank
+tensor. Similarly, a *scalar state* is an operator whose image is a
+scalar. Of particular interest is the vector force state
+:math:`\underline{\mathbf{T}}\left[ \mathbf{x},t \right]\left<
+\mathbf{x}^{\prime}-\mathbf{x} \right>`, which is a mapping, having
+units of force per volume squared, of the vector
+:math:`\mathbf{x}^{\prime}-\mathbf{x}` to the force vector state
+field. The vector state operator :math:`\underline{\mathbf{T}}` may
+itself be a function of :math:`\mathbf{x}` and :math:`t`. The
+constitutive model is completely contained within
+:math:`\underline{\mathbf{T}}`.
+
+In the peridynamic theory, the deformation at a point depends
+collectively on all points interacting with that point. Using the
+notation of :ref:`(Silling 2007) `, we write the
+peridynamic equation of motion as
+
+.. _periNewtonII:
+
+.. math::
+
+ \rho(\mathbf{x}) \ddot{\mathbf{u}}(\mathbf{x},t) =
+ \int_{\mathcal{H}_{\mathbf{x}}} \left\{
+ \underline{\mathbf{T}}\left[\mathbf{x},t
+ \right]\left<\mathbf{x}^{\prime}-\mathbf{x} \right> -
+ \underline{\mathbf{T}}\left[\mathbf{x}^{\prime},t
+ \right]\left<\mathbf{x}-\mathbf{x}^{\prime} \right> \right\}
+ {d}V_{\mathbf{x}^\prime} + \mathbf{b}(\mathbf{x},t), \qquad\qquad\textrm{(1)}
+
+where :math:`\rho` represents the mass density,
+:math:`\underline{\mathbf{T}}` the force vector state, and
+:math:`\mathbf{b}` an external body force density. A point
+:math:`\mathbf{x}` interacts with all the points
+:math:`\mathbf{x}^{\prime}` within the neighborhood
+:math:`\mathcal{H}_{\mathbf{x}}`, assumed to be a spherical region of
+radius :math:`\delta>0` centered at :math:`\mathbf{x}`. :math:`\delta`
+is called the *horizon*, and is analogous to the cutoff radius used in
+molecular dynamics. Conditions on :math:`\underline{\mathbf{T}}` for
+which :ref:`(1) ` satisfies the balance of linear and angular
+momentum are given in :ref:`(Silling 2007) `.
+
+We consider only force vector states that can be written as
+
+.. math::
+
+ \underline{\mathbf{T}} = \underline{t}\,\underline{\mathbf{M}},
+
+with :math:`\underline{t}` a *scalar force state* and
+:math:`\underline{\mathbf{M}}` the *deformed direction vector
+state*, defined by
+
+.. math::
+
+ \underline{\mathbf{M}}\left< \boldsymbol{\xi} \right> =
+ \left\{ \begin{array}{cl}
+ \frac{\boldsymbol{\xi} + \boldsymbol{\eta}}{
+ \left\Vert \boldsymbol{\xi} + \boldsymbol{\eta} \right\Vert
+ } & \left\Vert \boldsymbol{\xi} + \boldsymbol{\eta} \right\Vert \neq 0 \\
+ \boldsymbol{0} & \textrm{otherwise}
+ \end{array}
+ \right. . \qquad\qquad\textrm{(2)}
+
+Such force states correspond to so-called *ordinary* materials
+:ref:`(Silling 2007) `. These are the materials for which
+the force between any two interacting points :math:`\textbf{x}` and
+:math:`\textbf{x}^\prime` acts along the line between the points.
+
+
+Linear Peridynamic Solid (LPS) Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We summarize the linear peridynamic solid (LPS) material model. For more
+on this model, the reader is referred to :ref:`(Silling 2007)
+`. This model is a nonlocal analogue to a classical
+linear elastic isotropic material. The elastic properties of a a
+classical linear elastic isotropic material are determined by (for
+example) the bulk and shear moduli. For the LPS model, the elastic
+properties are analogously determined by the bulk and shear moduli,
+along with the horizon :math:`\delta`.
+
+The LPS model has a force scalar state
+
+.. math::
+
+ \underline{t} = \frac{3K\theta}{m}\underline{\omega}\,\underline{x} +
+ \alpha \underline{\omega}\,\underline{e}^{\rm d}, \qquad\qquad\textrm{(3)}
+
+with :math:`K` the bulk modulus and :math:`\alpha` related to the shear
+modulus :math:`G` as
+
+.. math::
+
+ \alpha = \frac{15 G}{m}.
+
+The remaining components of the model are described as follows. Define
+the reference position scalar state :math:`\underline{x}` so that
+:math:`\underline{x}\left<\boldsymbol{\xi} \right> = \left\Vert
+\boldsymbol{\xi} \right\Vert`. Then, the weighted volume :math:`m` is
+defined as
+
+.. math::
+
+ m\left[ \mathbf{x} \right] = \int_{\mathcal{H}_\mathbf{x}}
+ \underline{\omega} \left<\boldsymbol{\xi}\right>
+ \underline{x}\left<\boldsymbol{\xi} \right>
+ \underline{x}\left<\boldsymbol{\xi} \right>{d}V_{\boldsymbol{\xi} }. \qquad\qquad\textrm{(4)}
+
+Let
+
+.. math::
+
+ \underline{e}\left[ \mathbf{x},t \right] \left<\boldsymbol{\xi}
+ \right> = \left\Vert \boldsymbol{\xi} + \boldsymbol{\eta}
+ \right\Vert - \left\Vert \boldsymbol{\xi} \right\Vert
+
+be the extension scalar state, and
+
+.. math::
+
+ \theta\left[ \mathbf{x}, t \right] = \frac{3}{m\left[ \mathbf{x}
+ \right]}\int_{\mathcal{H}_\mathbf{x}} \underline{\omega}
+ \left<\boldsymbol{\xi}\right> \underline{x}\left<\boldsymbol{\xi}
+ \right> \underline{e}\left[ \mathbf{x},t
+ \right]\left<\boldsymbol{\xi} \right>{d}V_{\boldsymbol{\xi}}
+
+be the dilatation. The isotropic and deviatoric parts of the extension
+scalar state are defined, respectively, as
+
+.. math::
+
+ \underline{e}^{\rm i}=\frac{\theta \underline{x}}{3}, \qquad
+ \underline{e}^{\rm d} = \underline{e}- \underline{e}^{\rm i},
+
+
+where the arguments of the state functions and the vectors on which they
+operate are omitted for simplicity. We note that the LPS model is linear
+in the dilatation :math:`\theta`, and in the deviatoric part of the
+extension :math:`\underline{e}^{\rm d}`.
+
+.. note::
+
+ The weighted volume :math:`m` is time-independent, and does
+ not change as bonds break. It is computed with respect to the bond
+ family defined at the reference (initial) configuration.
+
+The non-negative scalar state :math:`\underline{\omega}` is an
+*influence function* :ref:`(Silling 2007) `. For more on
+influence functions, see :ref:`(Seleson 2010) `. If an
+influence function :math:`\underline{\omega}` depends only upon the
+scalar :math:`\left\Vert \boldsymbol{\xi} \right\Vert`, (i.e.,
+:math:`\underline{\omega}\left<\boldsymbol{\xi}\right> =
+\underline{\omega}\left<\left\Vert \boldsymbol{\xi} \right\Vert\right>`\
+), then :math:`\underline{\omega}` is a spherical influence function.
+For a spherical influence function, the LPS model is isotropic
+:ref:`(Silling 2007) `.
+
+.. note::
+
+ In the LAMMPS implementation of the LPS model, the influence function
+ :math:`\underline{\omega}\left<\left\Vert \boldsymbol{\xi}
+ \right\Vert\right> = 1 / \left\Vert \boldsymbol{\xi} \right\Vert` is
+ used. However, the user can define their own influence function by
+ altering the method "influence_function" in the file
+ ``pair_peri_lps.cpp``. The LAMMPS peridynamics code permits both
+ spherical and non-spherical influence functions (e.g., isotropic and
+ non-isotropic materials).
+
+
+Prototype Microelastic Brittle (PMB) Model
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We summarize the prototype microelastic brittle (PMB) material
+model. For more on this model, the reader is referred to
+:ref:`(Silling 2000) ` and :ref:`(Silling 2005)
+`. This model is a special case of the LPS model; see
+:ref:`(Seleson 2010) ` for the derivation. The elastic
+properties of the PMB model are determined by the bulk modulus :math:`K`
+and the horizon :math:`\delta`.
+
+The PMB model is expressed using the scalar force state field
+
+.. _periPMBState:
+
+.. math::
+
+ \underline{t}\left[ \mathbf{x},t \right]\left< \boldsymbol{\xi} \right> = \frac{1}{2} f\left( \boldsymbol{\eta} ,\boldsymbol{\xi} \right), \qquad\qquad\textrm{(5)}
+
+with :math:`f` a scalar-valued function. We assume that :math:`f` takes
+the form
+
+.. math::
+
+ f = c s,
+
+where
+
+.. _peric:
+
+.. math::
+
+ c = \frac{18K}{\pi \delta^4}, \qquad\qquad\textrm{(6)}
+
+with :math:`K` the bulk modulus and :math:`\delta` the horizon, and
+:math:`s` the bond stretch, defined as
+
+.. math::
+
+ s(t,\mathbf{\eta},\mathbf{\xi}) = \frac{ \left\Vert {\mathbf{\eta}+\mathbf{\xi}} \right\Vert - \left\Vert {\mathbf{\xi}} \right\Vert }{\left\Vert {\mathbf{\xi}} \right\Vert}.
+
+Bond stretch is a unitless quantity, and identical to a one-dimensional
+definition of strain. As such, we see that a bond at its equilibrium
+length has stretch :math:`s=0`, and a bond at twice its equilibrium
+length has stretch :math:`s=1`. The constant :math:`c` given above is
+appropriate for 3D models only. For more on the origins of the constant
+:math:`c`, see :ref:`(Silling 2005) `. For the derivation
+of :math:`c` for 1D and 2D models, see :ref:`(Emmrich) `.
+
+Given :ref:`(5) `, :ref:`(1) ` reduces to
+
+.. math::
+
+ \rho(\mathbf{x}) \ddot{\mathbf{u}}(\mathbf{x},t) = \int_{\mathcal{H}_\mathbf{x}} \mathbf{f} \left( \boldsymbol{\eta},\boldsymbol{\xi} \right){d}V_{\boldsymbol{\xi}} + \mathbf{b}(\mathbf{x},t), \qquad\qquad\textrm{(7)}
+
+with
+
+.. math::
+
+ \mathbf{f} \left( \boldsymbol{\eta}, \boldsymbol{\xi}\right) =f \left( \boldsymbol{\eta}, \boldsymbol{\xi}\right) \frac{\boldsymbol{\xi}+ \boldsymbol{\eta}}{ \left\Vert {\boldsymbol{\xi} + \boldsymbol{\eta}} \right\Vert}.
+
+Unlike the LPS model, the PMB model has a Poisson ratio of
+:math:`\nu=1/4` in 3D, and :math:`\nu=1/3` in 2D. This is reflected in
+the input for the PMB model, which requires only the bulk modulus of the
+material, whereas the LPS model requires both the bulk and shear moduli.
+
+.. _peridamage:
+
+Damage
+^^^^^^
+
+Bonds are made to break when they are stretched beyond a given
+limit. Once a bond fails, it is failed forever :ref:`(Silling)
+`. Further, new bonds are never created during the course
+of a simulation. We discuss only one criterion for bond breaking, called
+the *critical stretch* criterion.
+
+Define :math:`\mu` to be the history-dependent scalar
+boolean function
+
+.. _perimu:
+
+.. math::
+
+ \mu(t,\mathbf{\eta},\mathbf{\xi}) = \left\{
+ \begin{array}{cl}
+ 1 & \mbox{if $s(t^\prime,\mathbf{\eta},\mathbf{\xi})< \min \left(s_0(t^\prime,\mathbf{\eta},\mathbf{\xi}) , s_0(t^\prime,\mathbf{\eta}^\prime,\mathbf{\xi}^\prime) \right)$ for all $0 \leq t^\prime \leq t$} \\
+ 0 & \mbox{otherwise}
+ \end{array}\right\}. \qquad\qquad\textrm{(8)}
+
+where :math:`\mathbf{\eta}^\prime = \textbf{u}(\textbf{x}^{\prime
+\prime},t) - \textbf{u}(\textbf{x}^\prime,t)` and
+:math:`\mathbf{\xi}^\prime = \textbf{x}^{\prime \prime} -
+\textbf{x}^\prime`. Here, :math:`s_0(t,\mathbf{\eta},\mathbf{\xi})` is a
+critical stretch defined as
+
+.. _peris0:
+
+.. math::
+
+ s_0(t,\mathbf{\eta},\mathbf{\xi}) = s_{00} - \alpha s_{\min}(t,\mathbf{\eta},\mathbf{\xi}), \qquad s_{\min}(t) = \min_{\mathbf{\xi}} s(t,\mathbf{\eta},\mathbf{\xi}), \qquad\qquad\textrm{(9)}
+
+where :math:`s_{00}` and :math:`\alpha` are material-dependent
+constants. The history function :math:`\mu` breaks bonds when the
+stretch :math:`s` exceeds the critical stretch :math:`s_0`.
+
+Although :math:`s_0(t,\mathbf{\eta},\mathbf{\xi})` is expressed as a
+property of a particle, bond breaking must be a symmetric operation for
+all particle pairs sharing a bond. That is, particles :math:`\textbf{x}`
+and :math:`\textbf{x}^\prime` must utilize the same test when deciding
+to break their common bond. This can be done by any method that treats
+the particles symmetrically. In the definition of :math:`\mu` above, we
+have chosen to take the minimum of the two :math:`s_0` values for
+particles :math:`\textbf{x}` and :math:`\textbf{x}^\prime` when
+determining if the :math:`\textbf{x}`--:math:`\textbf{x}^\prime` bond
+should be broken.
+
+Following :ref:`(Silling) `, we can define the damage at a
+point :math:`\textbf{x}` as
+
+.. _peridamageeq:
+
+.. math::
+
+ \varphi(\textbf{x}, t) = 1 - \frac{\int_{\mathcal{H}_{\textbf{x}}} \mu(t,\mathbf{\eta},\mathbf{\xi}) dV_{\textbf{x}^\prime}
+ }{ \int_{\mathcal{H}_{\textbf{x}}} dV_{\textbf{x}^\prime} }. \qquad\qquad\textrm{(10)}
+
+Discrete Peridynamic Model and LAMMPS Implementation
+""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+In LAMMPS, instead of :ref:`(1) `, we model this equation of
+motion:
+
+.. math::
+
+ \rho(\mathbf{x}) \ddot{\textbf{y}}(\mathbf{x},t) = \int_{\mathcal{H}_{\mathbf{x}}}
+ \left\{ \underline{\mathbf{T}}\left[ \mathbf{x},t \right]\left<\mathbf{x}^{\prime}-\mathbf{x} \right>
+ - \underline{\mathbf{T}}\left[\mathbf{x}^{\prime},t \right]\left<\mathbf{x}-\mathbf{x}^{\prime} \right> \right\}
+ {d}V_{\mathbf{x}^\prime} + \mathbf{b}(\mathbf{x},t),
+
+where we explicitly track and store at each timestep the positions and
+not the displacements of the particles. We observe that
+:math:`\ddot{\textbf{y}}(\textbf{x}, t) = \ddot{\textbf{x}} +
+\ddot{\textbf{u}}(\textbf{x}, t) = \ddot{\textbf{u}}(\textbf{x}, t)`, so
+that this is equivalent to :ref:`(1) `.
+
+Spatial Discretization
+^^^^^^^^^^^^^^^^^^^^^^
+
+The region defining a peridynamic material is discretized into particles
+forming a simple cubic lattice with lattice constant :math:`\Delta x`,
+where each particle :math:`i` is associated with some volume fraction
+:math:`V_i`. For any particle :math:`i`, let :math:`\mathcal{F}_i`
+denote the family of particles for which particle :math:`i` shares a
+bond in the reference configuration. That is,
+
+.. _periBondFamily:
+
+.. math::
+
+ \mathcal{F}_i = \{ p ~ | ~ \left\Vert {\textbf{x}_p - \textbf{x}_i} \right\Vert \leq \delta \}. \qquad\qquad\textrm{(11)}
+
+The discretized equation of motion replaces :ref:`(1) ` with
+
+.. _peridiscreteNewtonII:
+
+.. math::
+
+ \rho \ddot{\textbf{y}}_i^n =
+ \sum_{p \in \mathcal{F}_i}
+ \left\{ \underline{\mathbf{T}}\left[ \textbf{x}_i,t \right]\left<\textbf{x}_p^{\prime}-\textbf{x}_i \right>
+ - \underline{\mathbf{T}}\left[\textbf{x}_p,t \right]\left<\textbf{x}_i-\textbf{x}_p \right> \right\}
+ V_{p} + \textbf{b}_i^n, \qquad\qquad\textrm{(12)}
+
+where :math:`n` is the timestep number and subscripts denote the particle number.
+
+Short-Range Forces
+^^^^^^^^^^^^^^^^^^
+
+In the model discussed so far, particles interact only through their
+bond forces. A particle with no bonds becomes a free non-interacting
+particle. To account for contact forces, short-range forces are
+introduced :ref:`(Silling 2007) `. We add to the force in
+:ref:`(12) ` the following force
+
+.. math::
+
+ \textbf{f}_S(\textbf{y}_p,\textbf{y}_i) = \min \left\{ 0, \frac{c_S}{\delta}(\left\Vert {\textbf{y}_p-\textbf{y}_i} \right\Vert - d_{pi}) \right\}
+ \frac{\textbf{y}_p-\textbf{y}_i}{\left\Vert {\textbf{y}_p-\textbf{y}_i} \right\Vert}, \qquad\qquad\textrm{(13)}
+
+where :math:`d_{pi}` is the short-range interaction distance between
+particles :math:`p` and :math:`i`, and :math:`c_S` is a multiple of the
+constant :math:`c` from :ref:`(6) `. Note that the short-range force
+is always repulsive, never attractive. In practice, we choose
+
+.. _pericS:
+
+.. math::
+
+ c_S = 15 \frac{18K}{\pi \delta^4}. \qquad\qquad\textrm{(14)}
+
+For the short-range interaction distance, we choose :ref:`(Silling 2007)
+`
+
+.. math::
+
+ d_{pi} = \min \left\{ 0.9 \left\Vert {\textbf{x}_p - \textbf{x}_i} \right\Vert, 1.35 (r_p + r_i) \right\}, \qquad\qquad\textrm{(15)}
+
+where :math:`r_i` is called the *node radius* of particle
+:math:`i`. Given a discrete lattice, we choose :math:`r_i` to be half
+the lattice constant.
+
+.. note::
+
+ For a simple cubic lattice, :math:`\Delta x = \Delta y = \Delta z`.
+
+Given this definition of :math:`d_{pi}`, contact forces appear only when
+particles are under compression.
+
+When accounting for short-range forces, it is convenient to define the
+short-range family of particles
+
+.. math::
+
+ \mathcal{F}^S_i = \{ p ~ | ~ \left\Vert {\textbf{y}_p - \textbf{y}_i} \right\Vert \leq d_{pi} \}.
+
+
+Modification to the Particle Volume
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The right-hand side of :ref:`(12) ` may be thought of as
+a midpoint quadrature of :ref:`(1) `. To slightly improve the
+accuracy of this quadrature, we discuss a modification to the particle
+volume used in :ref:`(12) `. In a situation where two
+particles share a bond with :math:`\left\Vert { \textbf{x}_p -
+\textbf{x}_i }\right\Vert = \delta`, for example, we suppose that only
+approximately half the volume of each particle is "seen" by the other
+:ref:`(Silling 2007) `. When computing the force of each
+particle on the other we use :math:`V_p / 2` rather than :math:`V_p` in
+:ref:`(12) `. As such, we introduce a nodal volume
+scaling function for all bonded particles where :math:`\delta - r_i \leq
+\left\Vert { \textbf{x}_p - \textbf{x}_i } \right\Vert \leq \delta` (see
+the Figure below).
+
+We choose to use a linear unitless nodal volume scaling function
+
+.. math::
+
+ \nu(\textbf{x}_p - \textbf{x}_i) = \left\{
+ \begin{array}{cl}
+ -\frac{1}{2 r_i} \left\Vert {\textbf{x}_p - \textbf{x}_i} \right\Vert + \left( \frac{\delta}{2 r_i} + \frac{1}{2} \right) & \mbox{if }
+ \delta - r_i \leq \left\Vert {\textbf{x}_p - \textbf{x}_i } \right\Vert \leq \delta \\
+ 1 & \mbox{if } \left\Vert {\textbf{x}_p - \textbf{x}_i } \right\Vert \leq \delta - r_i \\
+ 0 & \mbox{otherwise}
+ \end{array}
+ \right\}
+
+If :math:`\left\Vert {\textbf{x}_p - \textbf{x}_i} \right\Vert = \delta`, :math:`\nu = 0.5`, and if
+:math:`\left\Vert {\textbf{x}_p - \textbf{x}_i} \right\Vert = \delta - r_i`, :math:`\nu = 1.0`, for
+example.
+
+
+.. figure:: JPG/pdlammps_fig1.png
+ :figwidth: 80%
+ :figclass: align-center
+
+ Diagram showing horizon of a particular particle, demonstrating that
+ the volume associated with particles near the boundary of the horizon is
+ not completely contained within the horizon.
+
+Temporal Discretization
+^^^^^^^^^^^^^^^^^^^^^^^
+
+When discretizing time in LAMMPS, we use a velocity-Verlet scheme, where
+both the position and velocity of the particle are stored
+explicitly. The velocity-Verlet scheme is generally expressed in three
+steps. In :ref:`Algorithm 1 `, :math:`\rho_i` denotes the
+mass density of a particle and :math:`\widetilde{\textbf{f}}_i^n`
+denotes the the net force density on particle :math:`i` at timestep
+:math:`n`. The LAMMPS command :doc:`fix nve ` performs a
+velocity-Verlet integration.
+
+ .. _algvelverlet:
+
+ .. admonition:: Algorithm 1: Velocity Verlet
+ :class: tip
+
+ | 1: :math:`\textbf{v}_i^{n + 1/2} = \textbf{v}_i^n + \frac{\Delta t}{2 \rho_i} \widetilde{\textbf{f}}_i^n`
+ | 2: :math:`\textbf{y}_i^{n+1} = \textbf{y}_i^n + \Delta t \textbf{v}_i^{n + 1/2}`
+ | 3: :math:`\textbf{v}_i^{n+1} = \textbf{v}_i^{n+1/2} + \frac{\Delta t}{2 \rho_i} \widetilde{\textbf{f}}_i^{n+1}`
+
+Breaking Bonds
+^^^^^^^^^^^^^^
+
+During the course of simulation, it may be necessary to break bonds, as
+described in the :ref:`Damage section `. Bonds are recorded
+as broken in a simulation by removing them from the bond family
+:math:`\mathcal{F}_i` (see :ref:`(11) `).
+
+A naive implementation would have us first loop over all bonds and
+compute :math:`s_{min}` in :ref:`(9) `, then loop over all bonds
+again and break bonds with a stretch :math:`s > s0` as in
+:ref:`(8) `, and finally loop over all particles and compute forces
+for the next step of :ref:`Algorithm 1 `. For reasons of
+computational efficiency, we will utilize the values of :math:`s_0` from
+the *previous* timestep when deciding to break a bond.
+
+.. note::
+
+ For the first timestep, :math:`s_0` is initialized to
+ :math:`\mathbf{\infty}` for all nodes. This means that no bonds may
+ be broken until the second timestep. As such, it is recommended that
+ the first few timesteps of the peridynamic simulation not involve any
+ actions that might result in the breaking of bonds. As a practical
+ example, the projectile in the :ref:`commented example below
+ ` is placed such that it does not impact the target
+ brittle plate until several timesteps into the simulation.
+
+LPS Pseudocode
+^^^^^^^^^^^^^^
+
+A sketch of the LPS model implementation in the PERI package appears in
+:ref:`Algorithm 2 `. This algorithm makes use of the
+routines in :ref:`Algorithm 3 ` and :ref:`Algorithm 4
+`.
+
+ .. _algperilps:
+
+ .. admonition:: Algorithm 2: LPS Peridynamic Model Pseudocode
+ :class: tip
+
+ | Fix :math:`s_{00}`, :math:`\alpha`, horizon :math:`\delta`, bulk modulus :math:`K`, shear modulus :math:`G`, timestep :math:`\Delta t`, and generate initial lattice of particles with lattice constant :math:`\Delta x`. Let there be :math:`N` particles. Define constant :math:`c_S` for repulsive short-range forces.
+ | Initialize bonds between all particles :math:`i \neq j` where :math:`\left\Vert {\textbf{x}_j - \textbf{x}_i} \right\Vert \leq \delta`
+ | Initialize weighted volume :math:`m` for all particles using :ref:`Algorithm 3 `
+ | Initialize :math:`s_0 = \mathbf{\infty}` {*Initialize each entry to MAX_DOUBLE*}
+ | **while** not done **do**
+ | Perform step 1 of :ref:`Algorithm 1 `, updating velocities of all particles
+ | Perform step 2 of :ref:`Algorithm 1 `, updating positions of all particles
+ | :math:`\tilde{s}_0 = \mathbf{\infty}` {*Initialize each entry to MAX_DOUBLE*}
+ | **for** :math:`i=1` to :math:`N` **do**
+ | {Compute short-range forces}
+ | **for all** particles :math:`j \in \mathcal{F}^S_i` (the short-range family of nodes for particle :math:`i`) **do**
+ | :math:`r = \left\Vert {\textbf{y}_j - \textbf{y}_i} \right\Vert`
+ | :math:`dr = \min \{ 0, r - d \}` {*Short-range forces are only repulsive, never attractive*}
+ | :math:`k = \frac{c_S}{\delta} V_k dr` {:math:`c_S` *defined in :ref:`(14) `*}
+ | :math:`\textbf{f} = \textbf{f} + k \frac{\textbf{y}_j-\textbf{y}_i}{\left\Vert {\textbf{y}_j-\textbf{y}_i} \right\Vert}`
+ | **end for**
+ | **end for**
+ | Compute the dilatation for each particle using :ref:`Algorithm 4