ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'master' into user-dielectric

Browse Source
This commit is contained in:
Axel Kohlmeyer
2021-06-05 11:14:44 -04:00
parent f92bee868a d74d7cfd5f
commit 13b8c63e7a
4206 changed files with 130459 additions and 50114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
doc/src/Bibliography.rst
View File

@ -1129,6 +1129,9 @@ Bibliography
**(Sutmann)**
Sutmann, Arnold, Fahrenberger, et. al., Physical review / E 88(6), 063308 (2013)
**(Sutmann)** G. Sutmann. ScaFaCoS - a Scalable library of Fast Coulomb Solvers for particle Systems.
In Bajaj, Zavattieri, Koslowski, Siegmund, Proceedings of the Society of Engineering Science 51st Annual Technical Meeting. 2014.
**(Swinburne)**
Swinburne and Marinica, Physical Review Letters, 120, 1 (2018)
@ -1285,9 +1288,6 @@ Bibliography
**(Wennberg)**
Wennberg, Murtola, Hess, Lindahl, J Chem Theory Comput, 9, 3527 (2013).
**(Who)**
Who, Author2, Author3, J of Long Range Solvers, 35, 164-177 (2012).
**(Wicaksono1)**
Wicaksono, Sinclair, Militzer, Computational Materials Science, 117, 397-405 (2016).

50
doc/src/Build_development.rst
View File

@ -28,6 +28,28 @@ variable VERBOSE set to 1:
----------
.. _clang-tidy:
Enable static code analysis with clang-tidy
-------------------------------------------
The `clang-tidy tool <https://clang.llvm.org/extra/clang-tidy/>`_ is a
static code analysis tool to diagnose (and potentially fix) typical
programming errors or coding style violations. It has a modular framework
of tests that can be adjusted to help identifying problems before they
become bugs and also assist in modernizing large code bases (like LAMMPS).
It can be enabled for all C++ code with the following CMake flag
.. code-block:: bash
-D ENABLE_CLANG_TIDY=value # value = no (default) or yes
With this flag enabled all source files will be processed twice, first to
be compiled and then to be analyzed. Please note that the analysis can be
significantly more time consuming than the compilation itself.
----------
.. _iwyu_processing:
Report missing and unneeded '#include' statements
@ -447,12 +469,24 @@ The following options are available.
.. code-block:: bash
make check-whitespace # generate coverage report in HTML format
make fix-whitespace # generate coverage report in XML format
make check-permissions # delete folder with HTML format coverage report
make fix-permissions # delete all collected coverage data and HTML output
make check-whitespace # search for files with whitespace issues
make fix-whitespace # correct whitespace issues in files
make check-homepage # search for files with old LAMMPS homepage URLs
make fix-homepage # correct LAMMPS homepage URLs in files
make check-permissions # search for files with permissions issues
make fix-permissions # correct permissions issues in files
For the code in the ``unittest`` tree we are using the `clang-format`
tool (Clang version 8.0 or later is required). If available, the source
code files in the ``unittest`` tree can be updated to conform to the
formatting settings using ``make format-tests``.
For the code in the ``unittest`` and ``src`` trees we are transitioning
to use the `clang-format` tool to assist with having a consistent source
code style. The `clang-format` command bundled with Clang version 8.0
or later is required. The configuration is in files ``.clang-format``
in the respective folders. Since the modifications from `clang-format`
can be significant and - especially for "legacy style code" - also is
not always improving readability, a large number of files currently have
a ``// clang-format off`` at the top, which will disable the processing.
Over time, files will be refactored and updated to that `clang-format`
may be applied to them (at least in part).
If `clang-format` is available, the source code files in the ``unittest``
tree can be updated to conform to the formatting settings using
``make format-tests`` and the files in ``src`` with ``make format-src``.

98
doc/src/Build_extras.rst
View File

@ -48,7 +48,9 @@ This is the list of packages that may require additional steps.
* :ref:`USER-AWPMD <user-awpmd>`
* :ref:`USER-COLVARS <user-colvars>`
* :ref:`USER-H5MD <user-h5md>`
* :ref:`USER-HDNNP <user-hdnnp>`
* :ref:`USER-INTEL <user-intel>`
* :ref:`USER-MDI <user-mdi>`
* :ref:`USER-MESONT <user-mesont>`
* :ref:`USER-MOLFILE <user-molfile>`
* :ref:`USER-NETCDF <user-netcdf>`
@ -455,6 +457,9 @@ They must be specified in uppercase.
* - ZEN2
- HOST
- AMD Zen2 class CPU (AVX 2)
* - ZEN3
- HOST
- AMD Zen3 class CPU (AVX 2)
* - ARMV80
- HOST
- ARMv8.0 Compatible CPU
@ -467,6 +472,9 @@ They must be specified in uppercase.
* - ARMV8_THUNDERX2
- HOST
- ARMv8 Cavium ThunderX2 CPU
* - A64FX
- HOST
- ARMv8.2 with SVE Support
* - WSM
- HOST
- Intel Westmere CPU (SSE 4.2)
@ -539,6 +547,9 @@ They must be specified in uppercase.
* - AMPERE80
- GPU
- NVIDIA Ampere generation CC 8.0 GPU
* - AMPERE86
- GPU
- NVIDIA Ampere generation CC 8.6 GPU
* - VEGA900
- GPU
- AMD GPU MI25 GFX900
@ -547,12 +558,12 @@ They must be specified in uppercase.
- AMD GPU MI50/MI60 GFX906
* - VEGA908
- GPU
- AMD GPU GFX908
- AMD GPU MI100 GFX908
* - INTEL_GEN
- GPU
- Intel GPUs Gen9+
This list was last updated for version 3.3 of the Kokkos library.
This list was last updated for version 3.4.1 of the Kokkos library.
.. tabs::
@ -1463,6 +1474,60 @@ the HDF5 library.
----------
.. _user-hdnnp:
USER-HDNNP package
---------------------------------
To build with the USER-HDNNP package it is required to download and build the
external `n2p2 <https://github.com/CompPhysVienna/n2p2>`__ library ``v2.1.4``
(or higher). The LAMMPS build process offers an automatic download and
compilation of *n2p2* or allows you to choose the installation directory of
*n2p2* manually. Please see the boxes below for the CMake and traditional build
system for detailed information.
In case of a manual installation of *n2p2* you only need to build the *n2p2* core
library ``libnnp`` and interface library ``libnnpif``. When using GCC it should
suffice to execute ``make libnnpif`` in the *n2p2* ``src`` directory. For more
details please see ``lib/hdnnp/README`` and the `n2p2 build documentation
<https://compphysvienna.github.io/n2p2/topics/build.html>`__.
.. tabs::
.. tab:: CMake build
.. code-block:: bash
-D DOWNLOAD_N2P2=value # download n2p2 for build, value = no (default) or yes
-D N2P2_DIR=path # n2p2 base directory (only needed if a custom location)
If ``DOWNLOAD_N2P2`` is set, the *n2p2* library will be downloaded and
built inside the CMake build directory. If the *n2p2* library is already
on your system (in a location CMake cannot find it), set the ``N2P2_DIR``
to path where *n2p2* is located. If *n2p2* is located directly in
``lib/hdnnp/n2p2`` it will be automatically found by CMake.
.. tab:: Traditional make
You can download and build the *n2p2* library manually if you prefer;
follow the instructions in ``lib/hdnnp/README``\ . You can also do it in
one step from the ``lammps/src`` dir, using a command like these, which
simply invoke the ``lib/hdnnp/Install.py`` script with the specified args:
.. code-block:: bash
$ make lib-hdnnp # print help message
$ make lib-hdnnp args="-b" # download and build in lib/hdnnp/n2p2-...
$ make lib-hdnnp args="-b -v 2.1.4" # download and build specific version
$ make lib-hdnnp args="-p /usr/local/n2p2" # use the existing n2p2 installation in /usr/local/n2p2
Note that 3 symbolic (soft) links, ``includelink``, ``liblink`` and
``Makefile.lammps``, will be created in ``lib/hdnnp`` to point to
``n2p2/include``, ``n2p2/lib`` and ``n2p2/lib/Makefile.lammps-extra``,
respectively. When LAMMPS is built in ``src`` it will use these links.
----------
.. _user-intel:
USER-INTEL package
@ -1533,6 +1598,35 @@ TBB and MKL.
----------
.. _user-mdi:
USER-MDI package
-----------------------------
.. tabs::
.. tab:: CMake build
.. code-block:: bash
-D DOWNLOAD_MDI=value # download MDI Library for build, value = no (default) or yes
.. tab:: Traditional make
Before building LAMMPS, you must build the MDI Library in
``lib/mdi``\ . You can do this by executing a command like one
of the following from the ``lib/mdi`` directory:
.. code-block:: bash
$ python Install.py -m gcc # build using gcc compiler
$ python Install.py -m icc # build using icc compiler
The build should produce two files: ``lib/mdi/includelink/mdi.h``
and ``lib/mdi/liblink/libmdi.so``\ .
----------
.. _user-mesont:
USER-MESONT package

31
doc/src/Build_manual.rst
View File

@ -28,29 +28,18 @@ If you downloaded LAMMPS as a tarball from `the LAMMPS website <lws_>`_,
the html folder and the PDF files should be included.
If you downloaded LAMMPS from the public git repository, then the HTML
and PDF files are not included. Instead you need to create them, in one
of two ways:
a. You can "fetch" the current HTML and PDF files from the LAMMPS web
site. Just type ``make fetch``. This should download a ``html_www``
directory and a ``Manual_www.pdf`` file. Note that if new LAMMPS features
have been added more recently than the date of your LAMMPS version, the
fetched documentation will include those changes (but your source code
will not, unless you update your local repository).
b. You can build the HTML or PDF files yourself, by typing ``make html``
or ``make pdf`` in the ``doc`` folder. This requires various tools
and files. Some of them have to be installed (see below). For the
rest the build process will attempt to download and install them into
a python virtual environment and local folders.
and PDF files are not included. You can build the HTML or PDF files yourself,
by typing ``make html`` or ``make pdf`` in the ``doc`` folder. This requires
various tools and files. Some of them have to be installed (see below). For
the rest the build process will attempt to download and install them into
a python virtual environment and local folders.
A current version of the manual (latest patch release, aka unstable
branch) is is available online at:
`https://lammps.sandia.gov/doc/Manual.html
<https://lammps.sandia.gov/doc/Manual.html>`_ A version of the manual
corresponding to the ongoing development (aka master branch) is
available online at: `https://docs.lammps.org/
<https://docs.lammps.org/>`_
`https://docs.lammps.org/Manual.html <https://docs.lammps.org/Manual.html>`_.
A version of the manual corresponding to the ongoing development (aka master branch)
is available online at: `https://docs.lammps.org/latest/
<https://docs.lammps.org/latest/>`_
Build using GNU make
--------------------
@ -257,4 +246,4 @@ the file ``lammps/doc/utils/sphinx-config/false_positives.txt``.
.. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html
.. _lws: https://lammps.sandia.gov
.. _lws: https://www.lammps.org

22
doc/src/Build_package.rst
View File

@ -30,17 +30,17 @@ steps, as explained on the :doc:`Build extras <Build_extras>` page.
These links take you to the extra instructions for those select
packages:
+--------------------------------------+--------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`COMPRESS <compress>` | :ref:`GPU <gpu>` | :ref:`KIM <kim>` | :ref:`KOKKOS <kokkos>` | :ref:`LATTE <latte>` | :ref:`MESSAGE <message>` |
+--------------------------------------+--------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`MSCG <mscg>` | :ref:`OPT <opt>` | :ref:`POEMS <poems>` | :ref:`PYTHON <python>` | :ref:`VORONOI <voronoi>` | :ref:`USER-ADIOS <user-adios>` |
+--------------------------------------+--------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`USER-ATC <user-atc>` | :ref:`USER-AWPMD <user-awpmd>` | :ref:`USER-COLVARS <user-colvars>` | :ref:`USER-H5MD <user-h5md>` | :ref:`USER-INTEL <user-intel>` | :ref:`USER-MOLFILE <user-molfile>` |
+--------------------------------------+--------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`USER-NETCDF <user-netcdf>` | :ref:`USER-PACE <user-pace>` | :ref:`USER-PLUMED <user-plumed>` | :ref:`USER-OMP <user-omp>` | :ref:`USER-QMMM <user-qmmm>` | :ref:`USER-QUIP <user-quip>` |
+--------------------------------------+--------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
| :ref:`USER-SCAFACOS <user-scafacos>` | :ref:`USER-SMD <user-smd>` | :ref:`USER-VTK <user-vtk>` | | | |
+--------------------------------------+--------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+
+--------------------------------------+--------------------------------------+------------------------------------+----------------------------------+--------------------------------+--------------------------------+
| :ref:`COMPRESS <compress>` | :ref:`GPU <gpu>` | :ref:`KIM <kim>` | :ref:`KOKKOS <kokkos>` | :ref:`LATTE <latte>` | :ref:`MESSAGE <message>` |
+--------------------------------------+--------------------------------------+------------------------------------+----------------------------------+--------------------------------+--------------------------------+
| :ref:`MSCG <mscg>` | :ref:`OPT <opt>` | :ref:`POEMS <poems>` | :ref:`PYTHON <python>` | :ref:`VORONOI <voronoi>` | :ref:`USER-ADIOS <user-adios>` |
+--------------------------------------+--------------------------------------+------------------------------------+----------------------------------+--------------------------------+--------------------------------+
| :ref:`USER-ATC <user-atc>` | :ref:`USER-AWPMD <user-awpmd>` | :ref:`USER-COLVARS <user-colvars>` | :ref:`USER-H5MD <user-h5md>` | :ref:`USER-HDNNP <user-hdnnp>` | :ref:`USER-INTEL <user-intel>` |
+--------------------------------------+--------------------------------------+------------------------------------+----------------------------------+--------------------------------+--------------------------------+
| :ref:`USER-MOLFILE <user-molfile>` | :ref:`USER-NETCDF <user-netcdf>` | :ref:`USER-PACE <user-pace>` | :ref:`USER-PLUMED <user-plumed>` | :ref:`USER-OMP <user-omp>` | :ref:`USER-QMMM <user-qmmm>` |
+--------------------------------------+--------------------------------------+------------------------------------+----------------------------------+--------------------------------+--------------------------------+
| :ref:`USER-QUIP <user-quip>` | :ref:`USER-SCAFACOS <user-scafacos>` | :ref:`USER-SMD <user-smd>` | :ref:`USER-VTK <user-vtk>` | | |
+--------------------------------------+--------------------------------------+------------------------------------+----------------------------------+--------------------------------+--------------------------------+
The mechanism for including packages is simple but different for CMake
versus make.

1
doc/src/Commands_all.rst
View File

@ -67,6 +67,7 @@ An alphabetic list of all general LAMMPS commands.
* :doc:`lattice <lattice>`
* :doc:`log <log>`
* :doc:`mass <mass>`
* :doc:`mdi/engine <mdi_engine>`
* :doc:`message <message>`
* :doc:`minimize <minimize>`
* :doc:`min_modify <min_modify>`

4
doc/src/Commands_fix.rst
View File

@ -39,6 +39,9 @@ OPT.
* :doc:`ave/time <fix_ave_time>`
* :doc:`aveforce <fix_aveforce>`
* :doc:`balance <fix_balance>`
* :doc:`brownian <fix_brownian>`
* :doc:`brownian/asphere <fix_brownian>`
* :doc:`brownian/sphere <fix_brownian>`
* :doc:`bocs <fix_bocs>`
* :doc:`bond/break <fix_bond_break>`
* :doc:`bond/create <fix_bond_create>`
@ -98,6 +101,7 @@ OPT.
* :doc:`lb/viscous <fix_lb_viscous>`
* :doc:`lineforce <fix_lineforce>`
* :doc:`manifoldforce <fix_manifoldforce>`
* :doc:`mdi/engine <fix_mdi_engine>`
* :doc:`meso/move <fix_meso_move>`
* :doc:`momentum (k) <fix_momentum>`
* :doc:`momentum/chunk <fix_momentum>`

6
doc/src/Commands_pair.rst
View File

@ -87,6 +87,8 @@ OPT.
* :doc:`coul/wolf/cs <pair_cs>`
* :doc:`dpd (gio) <pair_dpd>`
* :doc:`dpd/fdt <pair_dpd_fdt>`
* :doc:`dpd/ext <pair_dpd_ext>`
* :doc:`dpd/ext/tstat <pair_dpd_ext>`
* :doc:`dpd/fdt/energy (k) <pair_dpd_fdt>`
* :doc:`dpd/tstat (go) <pair_dpd>`
* :doc:`dsmc <pair_dsmc>`
@ -116,6 +118,7 @@ OPT.
* :doc:`gw/zbl <pair_gw>`
* :doc:`hbond/dreiding/lj (o) <pair_hbond_dreiding>`
* :doc:`hbond/dreiding/morse (o) <pair_hbond_dreiding>`
* :doc:`hdnnp <pair_hdnnp>`
* :doc:`ilp/graphene/hbn <pair_ilp_graphene_hbn>`
* :doc:`kolmogorov/crespi/full <pair_kolmogorov_crespi_full>`
* :doc:`kolmogorov/crespi/z <pair_kolmogorov_crespi_z>`
@ -169,7 +172,7 @@ OPT.
* :doc:`lj/sdk/coul/long (go) <pair_sdk>`
* :doc:`lj/sdk/coul/msm (o) <pair_sdk>`
* :doc:`lj/sf/dipole/sf (go) <pair_dipole>`
* :doc:`lj/smooth (o) <pair_lj_smooth>`
* :doc:`lj/smooth (go) <pair_lj_smooth>`
* :doc:`lj/smooth/linear (o) <pair_lj_smooth_linear>`
* :doc:`lj/switch3/coulgauss/long <pair_lj_switch3_coulgauss_long>`
* :doc:`lj96/cut (go) <pair_lj96>`
@ -224,6 +227,7 @@ OPT.
* :doc:`polymorphic <pair_polymorphic>`
* :doc:`python <pair_python>`
* :doc:`quip <pair_quip>`
* :doc:`rann <pair_rann>`
* :doc:`reax/c (ko) <pair_reaxc>`
* :doc:`rebo (io) <pair_airebo>`
* :doc:`resquared (go) <pair_resquared>`

40
doc/src/Developer_utils.rst
View File

@ -9,14 +9,29 @@ reading or writing to files with error checking or translation of
strings into specific types of numbers with checking for validity. This
reduces redundant implementations and encourages consistent behavior.
I/O with status check
^^^^^^^^^^^^^^^^^^^^^
I/O with status check and similar functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
These are wrappers around the corresponding C library calls like
``fgets()`` or ``fread()``. They will check if there were errors
on reading or an unexpected end-of-file state was reached. In that
case, the functions will stop the calculation with an error message,
indicating the name of the problematic file, if possible.
The the first two functions are wrappers around the corresponding C
library calls ``fgets()`` or ``fread()``. They will check if there
were errors on reading or an unexpected end-of-file state was reached.
In that case, the functions will stop with an error message, indicating
the name of the problematic file, if possible unless the *error* argument
is a NULL pointer.
The :cpp:func:`fgets_trunc` function will work similar for ``fgets()``
but it will read in a whole line (i.e. until the end of line or end
of file), but store only as many characters as will fit into the buffer
including a final newline character and the terminating NULL byte.
If the line in the file is longer it will thus be truncated in the buffer.
This function is used by :cpp:func:`read_lines_from_file` to read individual
lines but make certain they follow the size constraints.
The :cpp:func:`read_lines_from_file` function will read the requested
number of lines of a maximum length into a buffer and will return 0
if successful or 1 if not. It also guarantees that all lines are
terminated with a newline character and the entire buffer with a
NULL character.
----------
@ -26,6 +41,12 @@ indicating the name of the problematic file, if possible.
.. doxygenfunction:: sfread
:project: progguide
.. doxygenfunction:: fgets_trunc
:project: progguide
.. doxygenfunction:: read_lines_from_file
:project: progguide
----------
String to number conversions with validity check
@ -164,7 +185,10 @@ Argument processing
Convenience functions
^^^^^^^^^^^^^^^^^^^^^
.. doxygenfunction:: logmesg
.. doxygenfunction:: logmesg(LAMMPS *lmp, const S &format, Args&&... args)
:project: progguide
.. doxygenfunction:: logmesg(LAMMPS *lmp, const std::string &mesg)
:project: progguide
.. doxygenfunction:: getsyserror

6
doc/src/Errors_bugs.rst
View File

@ -5,8 +5,8 @@ If you are confident that you have found a bug in LAMMPS, please follow
the steps outlined below:
* Check the `New features and bug fixes
<https://lammps.sandia.gov/bug.html>`_ section of the `LAMMPS WWW site
<https://lammps.sandia.gov>`_ or the
<https://www.lammps.org/bug.html>`_ section of the `LAMMPS WWW site
<https://www.lammps.org>`_ or the
`GitHub Releases page <https://github.com/lammps/lammps/releases>`_ to
see if the bug has already been addressed in a patch release.
* Check that your issue can be reproduced with the latest development
@ -17,7 +17,7 @@ the steps outlined below:
if your issue has already been reported and if it is still open.
* Check the `GitHub Pull Requests page <https://github.com/lammps/lammps/pulls>`_
to see if there is already a fix for your bug pending.
* Check the `mailing list archives <https://lammps.sandia.gov/mail.html>`_
* Check the `mailing list archives <https://www.lammps.org/mail.html>`_
to see if the issue has been discussed before.
If none of these steps yields any useful information, please file a new

2
doc/src/Errors_common.rst
View File

@ -39,7 +39,7 @@ figure out your physics or numerical mistakes, like choosing too big a
timestep, specifying erroneous force field coefficients, or putting 2
atoms on top of each other! If you run into errors that LAMMPS
does not catch that you think it should flag, please send an email to
the `developers <https://lammps.sandia.gov/authors.html>`_.
the `developers <https://www.lammps.org/authors.html>`_.
If you get an error message about an invalid command in your input
script, you can determine what command is causing the problem by

2
doc/src/Errors_messages.rst
View File

@ -3871,7 +3871,7 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
*Fix orient/fcc found self twice*
The neighbor lists used by fix orient/fcc are messed up. If this
error occurs, it is likely a bug, so send an email to the
`developers <https://lammps.sandia.gov/authors.html>`_.
`developers <https://www.lammps.org/authors.html>`_.
*Fix peri neigh does not exist*
Somehow a fix that the pair style defines has been deleted.

8
doc/src/Examples.rst
View File

@ -18,7 +18,7 @@ files and image files.
If you uncomment the :doc:`dump <dump>` command in the input script, a
text dump file will be produced, which can be animated by various
`visualization programs <https://lammps.sandia.gov/viz.html>`_.
`visualization programs <https://www.lammps.org/viz.html>`_.
If you uncomment the :doc:`dump image <dump>` command in the input
script, and assuming you have built LAMMPS with a JPG library, JPG
@ -27,7 +27,7 @@ be quickly post-processed into a movie using commands described on the
:doc:`dump image <dump_image>` doc page.
Animations of many of the examples can be viewed on the Movies section
of the `LAMMPS web site <https://lammps.sandia.gov/movies.html>`_.
of the `LAMMPS web site <https://www.lammps.org/movies.html>`_.
There are two kinds of sub-directories in the examples folder. Lower
case named directories contain one or a few simple, quick-to-run
@ -108,6 +108,8 @@ Lowercase directories
+-------------+------------------------------------------------------------------+
| msst | MSST shock dynamics |
+-------------+------------------------------------------------------------------+
| multi | multi neighboring for systems with large interaction disparities |
+-------------+------------------------------------------------------------------+
| nb3b | use of non-bonded 3-body harmonic pair style |
+-------------+------------------------------------------------------------------+
| neb | nudged elastic band (NEB) calculation for barrier finding |
@ -164,7 +166,7 @@ Here is how you can run and visualize one of the sample problems:
Running the simulation produces the files *dump.indent* and
*log.lammps*\ . You can visualize the dump file of snapshots with a
variety of third-party tools highlighted on the
`Visualization <https://lammps.sandia.gov/viz.html>`_ page of the LAMMPS
`Visualization <https://www.lammps.org/viz.html>`_ page of the LAMMPS
web site.
If you uncomment the :doc:`dump image <dump_image>` line(s) in the input

3
doc/src/Howto.rst
View File

@ -3,7 +3,7 @@ Howto discussions
These doc pages describe how to perform various tasks with LAMMPS,
both for users and developers. The
`glossary <https://lammps.sandia.gov/glossary.html>`_ website page also lists MD
`glossary <https://www.lammps.org/glossary.html>`_ website page also lists MD
terminology with links to corresponding LAMMPS manual pages. The
example input scripts included in the examples directory of the LAMMPS
distribution and highlighted on the :doc:`Examples <Examples>` doc page
@ -23,6 +23,7 @@ General howto
Howto_library
Howto_couple
Howto_client_server
Howto_mdi
Settings howto
==============

2
doc/src/Howto_drude2.rst
View File

@ -9,6 +9,8 @@ USER-DRUDE package activated. Then, the data file and input scripts
have to be modified to include the Drude dipoles and how to handle
them.
Example input scripts available: examples/USER/drude
----------
**Overview of Drude induced dipoles**

132
doc/src/Howto_mdi.rst Normal file
View File

@ -0,0 +1,132 @@
Using LAMMPS with the MDI library for code coupling
===================================================
.. note::
This Howto doc page will eventually replace the
:doc:`Howto client/server <Howto_client_server>` doc page.
Client/server coupling of two codes is where one code is the "client"
and sends request messages (data) to a "server" code. The server
responds to each request with a reply message. This enables the two
codes to work in tandem to perform a simulation. LAMMPS can act as
either a client or server code; it does this by using the `MolSSI
Driver Interface (MDI) library
<https://molssi-mdi.github.io/MDI_Library/html/index.html>`_,
developed by the `Molecular Sciences Software Institute (MolSSI)
<https://molssi.org>`_.
Alternate methods for code coupling with LAMMPS are described on the
:doc:`Howto couple <Howto_couple>` doc page.
Some advantages of client/server coupling are that the two codes can run
as stand-alone executables; they need not be linked together. Thus
neither code needs to have a library interface. This also makes it easy
to run the two codes on different numbers of processors. If a message
protocol (format and content) is defined for a particular kind of
simulation, then in principle any code which implements the client-side
protocol can be used in tandem with any code which implements the
server-side protocol. Neither code needs to know what specific other
code it is working with.
In MDI nomenclature, a client code is the "driver", and a server code is
an "engine". One driver code can communicate with one or more instances
of one or more engine codes. Driver and engine codes can be written in
any language: C, C++, Fortran, Python, etc.
In addition to allowing driver and engine(s) running to run as
stand-alone executables, MDI also enables a server code to be a
"plugin" to the client code. In this scenario, server code(s) are
compiled as shared libraries, and one (or more) instances of the
server are instantiated by the driver code. If the driver code runs
in parallel, it can split its MPI communicator into multiple
sub-communicators, and launch each plugin engine instance on a
sub-communicator. Driver processors in that sub-communicator exchange
messages with that engine instance, and can also send MPI messages to
other processors in the driver. The driver code can also destroy
engine instances and re-instantiate them.
The way that a driver communicates with an engine is by making
MDI_Send() and MDI_Recv() calls, which are conceptually similar to
MPI_Send() and MPI_Recv() calls. Each send or receive has a string
which identifies the command name, and optionally some data, which can
be a single value or vector of values of any data type. Inside the
MDI library, data is exchanged between the driver and engine via MPI
calls or sockets. This a run-time choice by the user.
-------------
As an example, LAMMPS and the ``pw.x`` command from Quantum Espresso (a
suite of quantum DFT codes), can work together via the MDI library to
perform an ab initio MD (AIMD) simulation, where LAMMPS runs an MD
simulation and sends a message each timestep to ``pw.x`` asking it to
compute quantum forces on the current configuration of atoms. Here is
how the 2 codes are launched to communicate by MPI:
.. code-block:: bash
% mpirun -np 2 lmp_mpi -mdi "-role DRIVER -name d -method MPI" \
-in in.aimd : -np 16 pw.x -in qe.in -mdi "-role ENGINE -name e -method MPI"
In this case LAMMPS runs on 2 processors (MPI tasks), ``pw.x`` runs on 16
processors.
Here is how the 2 codes are launched to communicate by sockets:
.. code-block:: bash
% mpirun -np 2 lmp_mpi -mdi "-role DRIVER -name d -method TCP -port 8021" -in in.aimd
% mpirun -np 16 pw.x -in qe.in -mdi "-role ENGINE -name e -method TCP -port 8021 -hostname localhost"
These commands could be issued in different windows on a desktop
machine. Or in the same window, if the first command is ended with
"&" so as to run in the background. If "localhost" is replaced by an
IP address, ``pw.x`` could be run on another machine on the same network, or
even on another machine across the country.
After both codes initialize themselves to model the same system, this is
what occurs each timestep:
* LAMMPS send a ">COORDS" message to ``pw.x`` with a 3*N vector of current atom coords
* ``pw.x`` receives the message/coords and computes quantum forces on all the atoms
* LAMMPS send a "<FORCES" message to ``pw.x`` and waits for the result
* ``pw.x`` receives the message (after its computation finishes) and sends a 3*N vector of forces
* LAMMPS receives the forces and time integrates to complete a single timestep
-------------
Examples scripts for using LAMMPS as an MDI engine are in the
examples/mdi directory. See the README file in that directory for
instructions on how to run the examples.
.. note::
Work is underway to add commands that allow LAMMPS to be used as an
MDI driver, e.g. for the AIMD example discussed above. Example
scripts for this usage mode will be added the same directory when
available.
If LAMMPS is used as a stand-alone engine it should set up the system
it will be modeling in its input script, then invoke the
:doc:`mdi/engine <mdi_engine>` command. This will put LAMMPS into
"engine mode" where it waits for messages and data from the driver.
When the driver sends an "EXIT" command, LAMMPS will exit engine mode
and the input script will continue.
If LAMMPS is used as a plugin engine it operates the same way, except
that the driver will pass LAMMPS an input script to initialize itself.
Upon receiving the "EXIT" command, LAMMPS will exit engine mode and the
input script will continue. After finishing execution of the input
script, the instance of LAMMPS will be destroyed.
LAMMPS supports the full set of MD-appropriate engine commands defined
by the MDI library. See the :doc:`mdi/engine <mdi_engine>` doc page for
a list of these.
If those commands are not sufficient for a user-developed driver to use
LAMMPS as an engine, then new commands can be easily added. See these
two files which implement the definition of MDI commands and the logic
for responding to them:
* src/MDI/mdi_engine.cpp
* src/MDI/fix_mdi_engine.cpp

2
doc/src/Howto_wsl.rst
View File

@ -201,7 +201,7 @@ build configuration and any binaries generated during compilation.
There are countless ways to compile LAMMPS. It is beyond the scope of this
tutorial. If you want to find out more about what can be enabled, please
consult the extensive `documentation <https://lammps.sandia.gov/doc/Build_cmake.html>`_.
consult the extensive `documentation <https://docs.lammps.org/Build_cmake.html>`_.
To compile a minimal version of LAMMPS, we're going to use a preset.
Presets are a way to specify a collection of CMake options using a file.

2
doc/src/Install_git.rst
View File

@ -78,7 +78,7 @@ this is as follows.
$ git checkout tagID
Stable versions and what tagID to use for a particular stable version
are discussed on `this page <https://lammps.sandia.gov/bug.html#version>`_.
are discussed on `this page <https://www.lammps.org/bug.html#version>`_.
Note that this command will print some warnings, because in order to get
back to the latest revision and to be able to update with ``git pull``
again, you will need to do ``git checkout unstable`` (or

2
doc/src/Install_patch.rst
View File

@ -10,7 +10,7 @@ If you prefer to download a tarball, as described on the
:doc:`tarball download <Install_tarball>` page, you can stay current by
downloading "patch files" when new patch releases are made. A link to
a patch file is posted on the
`bug fixes and new feature page <https://lammps.sandia.gov/bug.html>`_
`bug fixes and new feature page <https://www.lammps.org/bug.html>`_
of the LAMMPS website, along
with a list of changed files and details about what is in the new patch
release. This page explains how to apply the patch file to your local

8
doc/src/Install_tarball.rst
View File

@ -4,10 +4,10 @@ Download source and documentation as a tarball
You can download a current LAMMPS tarball from the `download page <download_>`_
of the `LAMMPS website <lws_>`_.
.. _download: https://lammps.sandia.gov/download.html
.. _bug: https://lammps.sandia.gov/bug.html
.. _older: https://lammps.sandia.gov/tars
.. _lws: https://lammps.sandia.gov
.. _download: https://www.lammps.org/download.html
.. _bug: https://www.lammps.org/bug.html
.. _older: https://www.lammps.org/tars
.. _lws: https://www.lammps.org
You have two choices of tarballs, either the most recent stable
release or the most current patch release. Stable releases occur a

6
doc/src/Intro_authors.rst
View File

@ -11,14 +11,14 @@ University:
* Richard Berger, richard.berger at temple.edu
.. _sjp: http://www.cs.sandia.gov/~sjplimp
.. _lws: https://lammps.sandia.gov
.. _lws: https://www.lammps.org
Past developers include Paul Crozier and Mark Stevens, both at Sandia,
and Ray Shan, now at Materials Design.
----------
The `Authors page <https://lammps.sandia.gov/authors.html>`_ of the
The `Authors page <https://www.lammps.org/authors.html>`_ of the
`LAMMPS website <lws_>`_ has a comprehensive list of all the individuals
who have contributed code for a new feature or command or tool to
LAMMPS.
@ -46,7 +46,7 @@ general-purpose as it is without their expertise and efforts.
----------
As discussed on the `History page <https://lammps.sandia.gov/history.html>`_ of the website, LAMMPS
As discussed on the `History page <https://www.lammps.org/history.html>`_ of the website, LAMMPS
originated as a cooperative project between DOE labs and industrial
partners. Folks involved in the design and testing of the original
version of LAMMPS were the following:

4
doc/src/Intro_citing.rst
View File

@ -38,8 +38,8 @@ In addition there are DOIs for individual stable releases. Currently there are:
Home page
^^^^^^^^^
The LAMMPS website at `https://lammps.sandia.gov/
<https://lammps.sandia.gov>`_ is the canonical location for information
The LAMMPS website at `https://www.lammps.org/
<https://www.lammps.org>`_ is the canonical location for information
about LAMMPS and its features.
Citing contributions

4
doc/src/Intro_nonfeatures.rst
View File

@ -33,7 +33,7 @@ Here are suggestions on how to perform these tasks:
linear bead-spring polymer chains. The moltemplate program is a true
molecular builder that will generate complex molecular models. See
the :doc:`Tools <Tools>` doc page for details on tools packaged with
LAMMPS. The `Pre/post processing page <http:/lammps.sandia.gov/prepost.html>`_ of the LAMMPS website
LAMMPS. The `Pre/post processing page <http:/www.lammps.org/prepost.html>`_ of the LAMMPS website
describes a variety of third party tools for this task. Furthermore,
some LAMMPS internal commands allow to reconstruct, or selectively add
topology information, as well as provide the option to insert molecule
@ -67,7 +67,7 @@ Here are suggestions on how to perform these tasks:
them to an external program, `FFmpeg <https://www.ffmpeg.org>`_ to generate
movies from them. For high-quality, interactive visualization there are
many excellent and free tools available. See the
`Visualization Tools <https://lammps.sandia.gov/viz.html>`_ page of the
`Visualization Tools <https://www.lammps.org/viz.html>`_ page of the
LAMMPS website for
visualization packages that can process LAMMPS output data.
* **Plotting:** See the next bullet about Pizza.py as well as the

30
doc/src/Intro_opensource.rst
View File

@ -2,18 +2,20 @@ LAMMPS open-source license
--------------------------
LAMMPS is a freely-available open-source code, distributed under the
terms of the `GNU Public License <gnu_>`_, which means you can use or
modify the code however you wish.
terms of the `GNU Public License Version 2 <gpl_>`_, which means you can
use or modify the code however you wish for your own purposes, but have
to adhere to certain rules when redistributing it or software derived
from it or that includes parts of it.
LAMMPS comes with no warranty of any kind. As each source file states
in its header, it is a copyrighted code that is distributed free-of-
charge, under the terms of the `GNU Public License <gnu_>`_ (GPL). This
is often referred to as open-source distribution - see
`www.gnu.org <gnuorg_>`_ or `www.opensource.org <opensource_>`_. The legal
text of the GPL is in the LICENSE file included in the LAMMPS
charge, under the terms of the `GNU Public License Version 2 <gpl_>`_
(GPLv2). This is often referred to as open-source distribution - see
`www.gnu.org <gnuorg_>`_ or `www.opensource.org <opensource_>`_. The
legal text of the GPL is in the LICENSE file included in the LAMMPS
distribution.
.. _gnu: http://www.gnu.org/copyleft/gpl.html
.. _gpl: https://github.com/lammps/lammps/blob/master/LICENSE
.. _gnuorg: http://www.gnu.org
@ -24,14 +26,14 @@ Here is a summary of what the GPL means for LAMMPS users:
(1) Anyone is free to use, modify, or extend LAMMPS in any way they
choose, including for commercial purposes.
(2) If you distribute a modified version of LAMMPS, it must remain
open-source, meaning you distribute it under the terms of the GPL.
You should clearly annotate such a code as a derivative version of
LAMMPS.
(2) If you **distribute** a modified version of LAMMPS, it must remain
open-source, meaning you distribute **all** of it under the terms of
the GPL. You should clearly annotate such a code as a derivative version
of LAMMPS.
(3) If you release any code that includes LAMMPS source code, then it
must also be open-sourced, meaning you distribute it under the terms
of the GPL.
(3) If you release any code that includes or uses LAMMPS source code,
then it must also be open-sourced, meaning you distribute it under
the terms of the GPL.
(4) If you give LAMMPS files to someone else, the GPL LICENSE file and
source file headers (including the copyright and GPL notices) should

4
doc/src/Intro_overview.rst
View File

@ -16,10 +16,10 @@ shared-memory boxes and distributed-memory clusters and
supercomputers.
.. _mpi: https://en.wikipedia.org/wiki/Message_Passing_Interface
.. _lws: https://lammps.sandia.gov
.. _lws: https://www.lammps.org
LAMMPS is written in C++. Earlier versions were written in F77 and
F90. See the `History page <https://lammps.sandia.gov/history.html>`_ of
F90. See the `History page <https://www.lammps.org/history.html>`_ of
the website for details. All versions can be downloaded from the
`LAMMPS website <lws_>`_.

40
doc/src/Intro_website.rst
View File

@ -5,31 +5,31 @@ The `LAMMPS website <lws_>`_ has a variety of additional info about
LAMMPS, beyond what is in this manual. Some other useful resources
available online are listed below.
.. _lws: https://lammps.sandia.gov
.. _lws: https://www.lammps.org
* `Brief intro and recently added significant features <lws_>`_
* `List of features <https://lammps.sandia.gov/doc/Intro_features.html>`_
* `List of non-features <https://lammps.sandia.gov/doc/Intro_nonfeatures.html>`_
* `Recent bug fixes and new features <https://lammps.sandia.gov/bug.html>`_
* `List of features <https://docs.lammps.org/Intro_features.html>`_
* `List of non-features <https://docs.lammps.org/Intro_nonfeatures.html>`_
* `Recent bug fixes and new features <https://www.lammps.org/bug.html>`_
* `Download info <https://lammps.sandia.gov/download.html>`_
* `Download info <https://www.lammps.org/download.html>`_
* `GitHub site <https://github.com/lammps/lammps>`_
* `SourceForge site <https://sourceforge.net/projects/lammps>`_
* `LAMMPS open-source license <https://lammps.sandia.gov/doc/Intro_opensource.html>`_
* `LAMMPS open-source license <https://docs.lammps.org/Intro_opensource.html>`_
* `Glossary of terms relevant to LAMMPS <https://lammps.sandia.gov/glossary.html>`_
* `LAMMPS highlights with images <https://lammps.sandia.gov/pictures.html>`_
* `LAMMPS highlights with movies <https://lammps.sandia.gov/movies.html>`_
* `Mail list <https://lammps.sandia.gov/mail.html>`_
* `Workshops <https://lammps.sandia.gov/workshops.html>`_
* `Tutorials <https://lammps.sandia.gov/tutorials.html>`_
* `Glossary of terms relevant to LAMMPS <https://www.lammps.org/glossary.html>`_
* `LAMMPS highlights with images <https://www.lammps.org/pictures.html>`_
* `LAMMPS highlights with movies <https://www.lammps.org/movies.html>`_
* `Mail list <https://www.lammps.org/mail.html>`_
* `Workshops <https://www.lammps.org/workshops.html>`_
* `Tutorials <https://www.lammps.org/tutorials.html>`_
* `Pre- and post-processing tools for LAMMPS <https://lammps.sandia.gov/prepost.html>`_
* `Other software usable with LAMMPS <https://lammps.sandia.gov/offsite.html>`_
* `Viz tools usable with LAMMPS <https://lammps.sandia.gov/viz.html>`_
* `Pre- and post-processing tools for LAMMPS <https://www.lammps.org/prepost.html>`_
* `Other software usable with LAMMPS <https://www.lammps.org/offsite.html>`_
* `Viz tools usable with LAMMPS <https://www.lammps.org/viz.html>`_
* `Benchmark performance <https://lammps.sandia.gov/bench.html>`_
* `Publications that have cited LAMMPS <https://lammps.sandia.gov/papers.html>`_
* `Authors of LAMMPS <https://lammps.sandia.gov/authors.html>`_
* `History of LAMMPS development <https://lammps.sandia.gov/history.html>`_
* `Funding for LAMMPS <https://lammps.sandia.gov/funding.html>`_
* `Benchmark performance <https://www.lammps.org/bench.html>`_
* `Publications that have cited LAMMPS <https://www.lammps.org/papers.html>`_
* `Authors of LAMMPS <https://www.lammps.org/authors.html>`_
* `History of LAMMPS development <https://www.lammps.org/history.html>`_
* `Funding for LAMMPS <https://www.lammps.org/funding.html>`_

12
doc/src/Library_config.rst
View File

@ -15,6 +15,8 @@ This section documents the following functions:
- :cpp:func:`lammps_config_package_count`
- :cpp:func:`lammps_config_package_name`
- :cpp:func:`lammps_config_accelerator`
- :cpp:func:`lammps_has_gpu_device`
- :cpp:func:`lammps_gpu_device_info`
- :cpp:func:`lammps_has_style`
- :cpp:func:`lammps_style_count`
- :cpp:func:`lammps_style_name`
@ -132,6 +134,16 @@ approach.
-----------------------
.. doxygenfunction:: lammps_has_gpu_device
:project: progguide
-----------------------
.. doxygenfunction:: lammps_get_gpu_device_info
:project: progguide
-----------------------
.. doxygenfunction:: lammps_has_style
:project: progguide

36
doc/src/Manual.rst
View File

@ -1,6 +1,6 @@
######################################
LAMMPS version |version| Documentation
######################################
########################################
LAMMPS Documentation (|version| version)
########################################
LAMMPS stands for **L**\ arge-scale **A**\ tomic/**M**\ olecular
**M**\ assively **P**\ arallel **S**\ imulator.
@ -11,11 +11,12 @@ computers. It was developed originally at Sandia National
Laboratories, a US Department of Energy facility. The majority of
funding for LAMMPS has come from the US Department of Energy (DOE).
LAMMPS is an open-source code, distributed freely under the terms of
the GNU Public License (GPL).
the GNU Public License Version 2 (GPLv2).
The `LAMMPS website <lws_>`_ has a variety of information about the
code. It includes links to an on-line version of this manual, a
`mailing list <https://lammps.sandia.gov/mail.html>`_ where users can
`mailing list <https://www.lammps.org/mail.html>`_ and
`online forum <https://www.lammps.org/forum.html>`_ where users can
post questions, and a `GitHub site <https://github.com/lammps/lammps>`_
where all LAMMPS development is coordinated.
@ -30,11 +31,13 @@ please :ref:`see this note <webbrowser>`.
-----------
The manual is organized in two parts:
The manual is organized in three parts:
1) the :ref:`User Guide <user_documentation>` for how to install
and use LAMMPS and 2) the :ref:`Programmer Guide <programmer_documentation>`
and use LAMMPS, 2) the :ref:`Programmer Guide <programmer_documentation>`
for how to write programs using the LAMMPS library from different
programming languages and how to modify and extend LAMMPS.
programming languages and how to modify and extend LAMMPS, and 3) the
:ref:`Command Reference <command_reference>` which includes detailed
descriptions of all commands included in the LAMMPS code.
.. only:: html
@ -42,7 +45,7 @@ programming languages and how to modify and extend LAMMPS.
:doc:`this page <Commands_all>` since it gives quick access
the documentation for all LAMMPS commands.
.. _lws: https://lammps.sandia.gov
.. _lws: https://www.lammps.org
----------
@ -89,10 +92,15 @@ Programmer Guide
Modify
Developer
*****************
Command Reference
*****************
.. _command_reference:
.. toctree::
:caption: Index
:name: index
:hidden:
:name: reference
:maxdepth: 1
:caption: Command Reference
commands_list
fixes
@ -118,10 +126,10 @@ Indices and tables
.. admonition:: Web Browser Compatibility
The HTML version of the manual makes use of advanced features present
int "modern" web browsers. This can lead to incompatibilities with older
in "modern" web browsers. This can lead to incompatibilities with older
web browsers (released more than 4 years ago) and specific vendor browsers
(e.g. Internet Explorer on Windows; Microsoft Edge works well though)
where parts of the pages are not rendered as expected (e.g. the layout is
broken or mathematical expressions not typeset). In that case we
recommend to install/use a different/newer web browser or use
the `PDF version of the manual <https://lammps.sandia.gov/doc/Manual.pdf>`_.
the `PDF version of the manual <https://docs.lammps.org/Manual.pdf>`_.

2
doc/src/Manual_version.rst
View File

@ -5,7 +5,7 @@ The LAMMPS "version" is the date when it was released, such as 1 May
2014. LAMMPS is updated continuously. Whenever we fix a bug or add a
feature, we release it in the next *patch* release, which are
typically made every couple of weeks. Info on patch releases are on
`this website page <https://lammps.sandia.gov/bug.html>`_. Every few
`this website page <https://www.lammps.org/bug.html>`_. Every few
months, the latest patch release is subjected to more thorough testing
and labeled as a *stable* version.

87
doc/src/Modify_contribute.rst
View File

@ -2,7 +2,7 @@ Submitting new features for inclusion in LAMMPS
===============================================
We encourage users to submit new features or modifications for LAMMPS to
`the core developers <https://lammps.sandia.gov/authors.html>`_ so they
`the core developers <https://www.lammps.org/authors.html>`_ so they
can be added to the LAMMPS distribution. The preferred way to manage and
coordinate this is via the LAMMPS project on `GitHub
<https://github.com/lammps/lammps>`_. Please see the :doc:`GitHub
@ -10,15 +10,15 @@ Tutorial <Howto_github>` for a demonstration on how to do that. An
alternative is to contact the LAMMPS developers or the indicated
developer of a package or feature directly and send in your contribution
via e-mail, but that can add a significant delay on getting your
contribution included, depending on how busy the developer is you
contact, how complex a task it would be to integrate that code, and how
contribution included, depending on how busy the respective developer
is, how complex a task it would be to integrate that code, and how
many - if any - changes are required before the code can be included.
For any larger modifications or programming project, you are encouraged
to contact the LAMMPS developers ahead of time, in order to discuss
implementation strategies and coding guidelines, that will make it
easier to integrate your contribution and result in less work for
everybody involved. You are also encouraged to search through the list
to contact the LAMMPS developers ahead of time in order to discuss
implementation strategies and coding guidelines. That will make it
easier to integrate your contribution and results in less work for
everybody involved. You are also encouraged to search through the list
of `open issues on GitHub <https://github.com/lammps/lammps/issues>`_
and submit a new issue for a planned feature, so you would not duplicate
the work of others (and possibly get scooped by them) or have your work
@ -31,21 +31,22 @@ send an e-mail to ``slack@lammps.org`` explaining what part of LAMMPS
you are working on. Only discussions related to LAMMPS development are
tolerated, so this is **NOT** for people that look for help with compiling,
installing, or using LAMMPS. Please contact the `lammps-users mailing
list <https://lammps.sandia.gov/mail.html>`_ for those purposes instead.
list <https://www.lammps.org/mail.html>`_ for those purposes instead.
How quickly your contribution will be integrated depends largely on how
much effort it will cause to integrate and test it, how much it requires
changes to the core codebase, and of how much interest it is to the
larger LAMMPS community. Please see below for a checklist of typical
requirements. Once you have prepared everything, see the :doc:`LAMMPS GitHub
Tutorial <Howto_github>` page for instructions on
how to submit your changes or new files through a GitHub pull
request. If you prefer to submit patches or full files, you should first
make certain, that your code works correctly with the latest patch-level
version of LAMMPS and contains all bug fixes from it. Then create a
gzipped tar file of all changed or added files or a corresponding patch
file using 'diff -u' or 'diff -c' and compress it with gzip. Please only
use gzip compression, as this works well on all platforms.
much effort it will cause to integrate and test it, how many and what
kind of changes it requires to the core codebase, and of how much
interest it is to the larger LAMMPS community. Please see below for a
checklist of typical requirements. Once you have prepared everything,
see the :doc:`LAMMPS GitHub Tutorial <Howto_github>` page for
instructions on how to submit your changes or new files through a GitHub
pull request. If you prefer to submit patches or full files, you should
first make certain, that your code works correctly with the latest
patch-level version of LAMMPS and contains all bug fixes from it. Then
create a gzipped tar file of all changed or added files or a
corresponding patch file using 'diff -u' or 'diff -c' and compress it
with gzip. Please only use gzip compression, as this works well and is
available on all platforms.
If the new features/files are broadly useful we may add them as core
files to LAMMPS or as part of a :doc:`standard package <Packages_standard>`. Else we will add them as a
@ -57,13 +58,16 @@ added to the LAMMPS distribution. All the standard and user packages
are listed and described on the :doc:`Packages details <Packages_details>` doc page.
Note that by providing us files to release, you are agreeing to make
them open-source, i.e. we can release them under the terms of the GPL,
used as a license for the rest of LAMMPS. See the :doc:`LAMMPS license
<Intro_opensource>` doc page for details.
them open-source, i.e. we can release them under the terms of the GPL
(version 2), used as a license for the rest of LAMMPS. And as part of
a LGPL (version 2.1) distribution that we make available to developers
on request only and with files that are authorized for that kind of
distribution removed (e.g. interface to FFTW). See the
:doc:`LAMMPS license <Intro_opensource>` doc page for details.
With user packages and files, all we are really providing (aside from
the fame and fortune that accompanies having your name in the source
code and on the `Authors page <https://lammps.sandia.gov/authors.html>`_
code and on the `Authors page <https://www.lammps.org/authors.html>`_
of the `LAMMPS WWW site <lws_>`_), is a means for you to distribute your
work to the LAMMPS user community, and a mechanism for others to
easily try out your new feature. This may help you find bugs or make
@ -77,13 +81,13 @@ unusual event).
If you prefer to actively develop and support your add-on
feature yourself, then you may wish to make it available for download
from your own website, as a user package that LAMMPS users can add to
their copy of LAMMPS. See the `Offsite LAMMPS packages and tools <https://lammps.sandia.gov/offsite.html>`_ page of the LAMMPS web
their copy of LAMMPS. See the `Offsite LAMMPS packages and tools <https://www.lammps.org/offsite.html>`_ page of the LAMMPS web
site for examples of groups that do this. We are happy to advertise
your package and web site from that page. Simply email the
`developers <https://lammps.sandia.gov/authors.html>`_ with info about
`developers <https://www.lammps.org/authors.html>`_ with info about
your package and we will post it there.
.. _lws: https://lammps.sandia.gov
.. _lws: https://www.lammps.org
The previous sections of this doc page describe how to add new "style"
files of various kinds to LAMMPS. Packages are simply collections of
@ -92,7 +96,7 @@ LAMMPS input script. If designed correctly, these additions typically
do not require changes to the main core of LAMMPS; they are simply
add-on files. If you think your new feature requires non-trivial
changes in core LAMMPS files, you should `communicate with the
developers <https://lammps.sandia.gov/authors.html>`_, since we may or
developers <https://www.lammps.org/authors.html>`_, since we may or
may not want to include those changes for some reason. An example of a
trivial change is making a parent-class method "virtual" when you derive
a new child class from it.
@ -112,7 +116,7 @@ packages in the src directory for examples. If you are uncertain, please ask.
your contribution(s) to be added to main LAMMPS code or one of its
standard packages, it needs to be written in a style compatible with
other LAMMPS source files. This means: 2-character indentation per
level, **no tabs**\ , no lines over 80 characters. I/O is done via
level, **no tabs**\ , no lines over 100 characters. I/O is done via
the C-style stdio library (mixing of stdio and iostreams is generally
discouraged), class header files should not import any system headers
outside of <cstdio>, STL containers should be avoided in headers,
@ -131,6 +135,31 @@ packages in the src directory for examples. If you are uncertain, please ask.
LAMMPS source files, including the use of the error class for error
and warning messages.
* To simplify reformatting contributed code in a way that is compatible
with the LAMMPS formatting styles, you can use clang-format (version 8
or later). The LAMMPS distribution includes a suitable ``.clang-format``
file which will be applied if you run ``clang-format -i some_file.cpp``
on your files inside the LAMMPS src tree. Please only reformat files
that you have contributed. For header files containing a
``SomeStyle(keyword, ClassName)`` macros it is required to have this
macro embedded with a pair of ``// clang-format off``, ``// clang-format on``
commends and the line must be terminated with a semi-colon (;).
Example:
.. code-block:: c++
#ifdef COMMAND_CLASS
// clang-format off
CommandStyle(run,Run);
// clang-format on
#else
#ifndef LMP_RUN_H
[...]
You may also use ``// clang-format on/off`` throughout your file
to protect sections of the file from being reformatted.
* If you want your contribution to be added as a user-contributed
feature, and it's a single file (actually a \*.cpp and \*.h file) it can
rapidly be added to the USER-MISC directory. Send us the one-line

168
doc/src/Packages_details.rst
View File

@ -69,6 +69,7 @@ page gives those details.
* :ref:`USER-ATC <PKG-USER-ATC>`
* :ref:`USER-AWPMD <PKG-USER-AWPMD>`
* :ref:`USER-BOCS <PKG-USER-BOCS>`
* :ref:`USER-BROWNIAN <PKG-USER-BROWNIAN>`
* :ref:`USER-CGDNA <PKG-USER-CGDNA>`
* :ref:`USER-CGSDK <PKG-USER-CGSDK>`
* :ref:`USER-COLVARS <PKG-USER-COLVARS>`
@ -78,9 +79,11 @@ page gives those details.
* :ref:`USER-EFF <PKG-USER-EFF>`
* :ref:`USER-FEP <PKG-USER-FEP>`
* :ref:`USER-H5MD <PKG-USER-H5MD>`
* :ref:`USER-HDNNP <PKG-USER-HDNNP>`
* :ref:`USER-INTEL <PKG-USER-INTEL>`
* :ref:`USER-LB <PKG-USER-LB>`
* :ref:`USER-MANIFOLD <PKG-USER-MANIFOLD>`
* :ref:`USER-MDI <PKG-USER-MDI>`
* :ref:`USER-MEAMC <PKG-USER-MEAMC>`
* :ref:`USER-MESODPD <PKG-USER-MESODPD>`
* :ref:`USER-MESONT <PKG-USER-MESONT>`
@ -97,6 +100,7 @@ page gives those details.
* :ref:`USER-QMMM <PKG-USER-QMMM>`
* :ref:`USER-QTB <PKG-USER-QTB>`
* :ref:`USER-QUIP <PKG-USER-QUIP>`
* :ref:`USER-RANN <PKG-USER-RANN>`
* :ref:`USER-REACTION <PKG-USER-REACTION>`
* :ref:`USER-REAXC <PKG-USER-REAXC>`
* :ref:`USER-SCAFACOS <PKG-USER-SCAFACOS>`
@ -131,8 +135,8 @@ particle models including ellipsoids, 2d lines, and 3d triangles.
* `doc/PDF/pair_resquared_extra.pdf <PDF/pair_resquared_extra.pdf>`_
* examples/ASPHERE
* examples/ellipse
* https://lammps.sandia.gov/movies.html#line
* https://lammps.sandia.gov/movies.html#tri
* https://www.lammps.org/movies.html#line
* https://www.lammps.org/movies.html#tri
----------
@ -328,7 +332,7 @@ This package has :ref:`specific installation instructions <gpu>` on the :doc:`Bu
* :doc:`package gpu <package>`
* :doc:`Commands <Commands_all>` pages (:doc:`pair <Commands_pair>`, :doc:`kspace <Commands_kspace>`)
for styles followed by (g)
* `Benchmarks page <https://lammps.sandia.gov/bench.html>`_ of web site
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of web site
----------
@ -354,11 +358,11 @@ potentials.
* examples/granregion
* examples/pour
* bench/in.chute
* https://lammps.sandia.gov/pictures.html#jamming
* https://lammps.sandia.gov/movies.html#hopper
* https://lammps.sandia.gov/movies.html#dem
* https://lammps.sandia.gov/movies.html#brazil
* https://lammps.sandia.gov/movies.html#granregion
* https://www.lammps.org/pictures.html#jamming
* https://www.lammps.org/movies.html#hopper
* https://www.lammps.org/movies.html#dem
* https://www.lammps.org/movies.html#brazil
* https://www.lammps.org/movies.html#granregion
----------
@ -445,7 +449,7 @@ time via the "-sf kk" or "-suffix kk" :doc:`command-line switches <Run_options>`
:ref:`USER-INTEL <PKG-USER-INTEL>`, and :ref:`USER-OMP <PKG-USER-OMP>` packages, which
have styles optimized for CPUs, KNLs, and GPUs.
You must have a C++11 compatible compiler to use this package.
You must have a C++14 compatible compiler to use this package.
KOKKOS makes extensive use of advanced C++ features, which can
expose compiler bugs, especially when compiling for maximum
performance at high optimization levels. Please see the file
@ -477,7 +481,7 @@ This package has :ref:`specific installation instructions <kokkos>` on the :doc:
* Search the :doc:`commands <Commands_all>` pages (:doc:`fix <Commands_fix>`, :doc:`compute <Commands_compute>`,
:doc:`pair <Commands_pair>`, :doc:`bond, angle, dihedral, improper <Commands_bond>`,
:doc:`kspace <Commands_kspace>`) for styles followed by (k)
* `Benchmarks page <https://lammps.sandia.gov/bench.html>`_ of web site
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of web site
----------
@ -601,7 +605,7 @@ bonds, for performing atomic swaps, and performing grand-canonical MC
* :doc:`fix tfmc <fix_tfmc>`
* :doc:`fix widom <fix_widom>`
* :doc:`pair_style dsmc <pair_dsmc>`
* https://lammps.sandia.gov/movies.html#gcmc
* https://www.lammps.org/movies.html#gcmc
----------
@ -658,8 +662,8 @@ listing, "ls src/MISC", to see the list of commands.
* :doc:`fix viscosity <fix_viscosity>`
* examples/KAPPA
* examples/VISCOSITY
* https://lammps.sandia.gov/pictures.html#ttm
* https://lammps.sandia.gov/movies.html#evaporation
* https://www.lammps.org/pictures.html#ttm
* https://www.lammps.org/movies.html#evaporation
----------
@ -814,7 +818,7 @@ This package has :ref:`specific installation instructions <opt>` on the :doc:`Bu
* :doc:`OPT package <Speed_opt>`
* :doc:`Section 2.6 -sf opt <Run_options>`
* Search the :doc:`pair style <Commands_pair>` page for styles followed by (t)
* `Benchmarks page <https://lammps.sandia.gov/bench.html>`_ of web site
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of web site
----------
@ -845,7 +849,7 @@ Foster (UTSA).
* :doc:`compute damage/atom <compute_damage_atom>`
* :doc:`compute plasticity/atom <compute_plasticity_atom>`
* examples/peri
* https://lammps.sandia.gov/movies.html#peri
* https://www.lammps.org/movies.html#peri
----------
@ -1006,8 +1010,8 @@ Also several computes which calculate properties of rigid bodies.
* examples/ASPHERE
* examples/rigid
* bench/in.rhodo
* https://lammps.sandia.gov/movies.html#box
* https://lammps.sandia.gov/movies.html#star
* https://www.lammps.org/movies.html#box
* https://www.lammps.org/movies.html#star
----------
@ -1108,9 +1112,9 @@ colloidal particles.
* :doc:`fix wall/srd <fix_wall_srd>`
* examples/srd
* examples/ASPHERE
* https://lammps.sandia.gov/movies.html#tri
* https://lammps.sandia.gov/movies.html#line
* https://lammps.sandia.gov/movies.html#poly
* https://www.lammps.org/movies.html#tri
* https://www.lammps.org/movies.html#line
* https://www.lammps.org/movies.html#poly
----------
@ -1202,7 +1206,7 @@ This package has :ref:`specific installation instructions <user-atc>` on the :do
* src/USER-ATC/README
* :doc:`fix atc <fix_atc>`
* examples/USER/atc
* https://lammps.sandia.gov/pictures.html#atc
* https://www.lammps.org/pictures.html#atc
----------
@ -1266,6 +1270,26 @@ Example inputs are in the examples/USER/bocs folder.
----------
.. _PKG-USER-BROWNIAN:
USER-BROWNIAN package
---------------------
**Contents:**
This package provides :doc:`fix brownian, fix brownian/sphere, and
fix brownian/asphere <fix_brownian>` as well as
:doc:`fix propel/self <fix_propel_self>` which allow to do Brownian
Dynamics time integration of point, spherical and aspherical particles
and also support self-propelled particles.
**Authors:** Sam Cameron (University of Bristol),
Stefan Paquay (while at Brandeis University) (initial version of fix propel/self)
Example inputs are in the examples/USER/brownian folder.
----------
.. _PKG-USER-CGDNA:
USER-CGDNA package
@ -1315,7 +1339,7 @@ acids.
* :doc:`pair_style lj/sdk/\* <pair_sdk>`
* :doc:`angle_style sdk <angle_sdk>`
* examples/USER/cgsdk
* https://lammps.sandia.gov/pictures.html#cg
* https://www.lammps.org/pictures.html#cg
----------
@ -1552,7 +1576,7 @@ tools/eff; see its README file.
* examples/USER/eff
* tools/eff/README
* tools/eff
* https://lammps.sandia.gov/movies.html#eff
* https://www.lammps.org/movies.html#eff
----------
@ -1617,6 +1641,39 @@ This package has :ref:`specific installation instructions <user-h5md>` on the :d
----------
.. _PKG-USER-HDNNP:
USER-HDNNP package
------------------
**Contents:**
A :doc:`pair_style hdnnp <pair_hdnnp>` command which allows to use
high-dimensional neural network potentials (HDNNPs), a form of machine learning
potentials. HDNNPs must be carefully trained prior to their application in a
molecular dynamics simulation.
.. _n2p2: https://github.com/CompPhysVienna/n2p2
To use this package you must have the `n2p2 <n2p2_>`_ library installed and
compiled on your system.
**Author:** Andreas Singraber
**Install:**
This package has :ref:`specific installation instructions <user-hdnnp>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
* src/USER-HDNNP: filenames -> commands
* src/USER-HDNNP/README
* lib/hdnnp/README
* :doc:`pair_style hdnnp <pair_hdnnp>`
* examples/USER/hdnnp
----------
.. _PKG-USER-INTEL:
USER-INTEL package
@ -1661,7 +1718,7 @@ This package has :ref:`specific installation instructions <user-intel>` on the :
* Search the :doc:`commands <Commands_all>` pages (:doc:`fix <Commands_fix>`, :doc:`compute <Commands_compute>`,
:doc:`pair <Commands_pair>`, :doc:`bond, angle, dihedral, improper <Commands_bond>`, :doc:`kspace <Commands_kspace>`) for styles followed by (i)
* src/USER-INTEL/TEST
* `Benchmarks page <https://lammps.sandia.gov/bench.html>`_ of web site
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of web site
----------
@ -1766,7 +1823,29 @@ Waltham, MA, USA)
* :doc:`fix nve/manifold/rattle <fix_nve_manifold_rattle>`
* :doc:`fix nvt/manifold/rattle <fix_nvt_manifold_rattle>`
* examples/USER/manifold
* https://lammps.sandia.gov/movies.html#manifold
* https://www.lammps.org/movies.html#manifold
----------
.. _PKG-USER-MDI:
USER-MDI package
----------------
**Contents:**
A LAMMPS command and fix to allow client-server coupling of LAMMPS to
other atomic or molecular simulation codes via the `MolSSI Driver Interface
(MDI) library <https://molssi-mdi.github.io/MDI_Library/html/index.html>`_.
**Author:** Taylor Barnes - MolSSI, taylor.a.barnes at gmail.com
**Supporting info:**
* src/USER-MDI/README
* :doc:`mdi/engine <mdi_engine>`
* :doc:`fix mdi/engine <fix_mdi_engine>`
* examples/USER/mdi
----------
@ -1822,10 +1901,10 @@ algorithm.
* :doc:`pair_style tdpd <pair_mesodpd>`
* :doc:`fix mvv/dpd <fix_mvv_dpd>`
* examples/USER/mesodpd
* https://lammps.sandia.gov/movies.html#mesodpd
* https://www.lammps.org/movies.html#mesodpd
* examples/USER/meso
* http://lammps.sandia.gov/movies.html#mesodpd
* http://www.lammps.org/movies.html#mesodpd
----------
@ -2041,7 +2120,7 @@ This package has :ref:`specific installation instructions <user-omp>` on the :do
* Search the :doc:`commands <Commands_all>` pages (:doc:`fix <Commands_fix>`, :doc:`compute <Commands_compute>`,
:doc:`pair <Commands_pair>`, :doc:`bond, angle, dihedral, improper <Commands_bond>`,
:doc:`kspace <Commands_kspace>`) for styles followed by (o)
* `Benchmarks page <https://lammps.sandia.gov/bench.html>`_ of web site
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of web site
----------
@ -2199,6 +2278,31 @@ This package has :ref:`specific installation instructions <user-quip>` on the :d
----------
.. _PKG-USER-RANN:
USER-RANN package
-----------------
**Contents:**
A pair style for using rapid atomistic neural network (RANN) potentials.
These neural network potentials work by first generating a series of symmetry
functions from the neighbor list and then using these values as the input layer
of a neural network.
**Authors:**
This package was written by Christopher Barrett
with contributions by Doyl Dickel, Mississippi State University.
**Supporting info:**
* src/USER-RANN: filenames -> commands
* :doc:`pair_style rann <pair_rann>`
* examples/USER/rann
----------
.. _PKG-USER-REACTION:
USER-REACTION package
@ -2224,8 +2328,8 @@ molecules, and chiral-sensitive reactions.
* src/USER-REACTION/README
* :doc:`fix bond/react <fix_bond_react>`
* examples/USER/reaction
* `2017 LAMMPS Workshop <https://lammps.sandia.gov/workshops/Aug17/pdf/gissinger.pdf>`_
* `2019 LAMMPS Workshop <https://lammps.sandia.gov/workshops/Aug19/talk_gissinger.pdf>`_
* `2017 LAMMPS Workshop <https://www.lammps.org/workshops/Aug17/pdf/gissinger.pdf>`_
* `2019 LAMMPS Workshop <https://www.lammps.org/workshops/Aug19/talk_gissinger.pdf>`_
* reacter.org
----------
@ -2352,7 +2456,7 @@ This package has :ref:`specific installation instructions <user-smd>` on the :do
* src/USER-SMD/README
* doc/PDF/SMD_LAMMPS_userguide.pdf
* examples/USER/smd
* https://lammps.sandia.gov/movies.html#smd
* https://www.lammps.org/movies.html#smd
----------
@ -2409,7 +2513,7 @@ Dynamics, Ernst Mach Institute, Germany).
* src/USER-SPH/README
* doc/PDF/SPH_LAMMPS_userguide.pdf
* examples/USER/sph
* https://lammps.sandia.gov/movies.html#sph
* https://www.lammps.org/movies.html#sph
----------

6
doc/src/Packages_standard.rst
View File

@ -39,13 +39,13 @@ package:
+----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
| :ref:`DIPOLE <PKG-DIPOLE>` | point dipole particles | :doc:`pair_style lj/.../dipole <pair_dipole>` | dipole | no |
+----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
| :ref:`GPU <PKG-GPU>` | GPU-enabled styles | :doc:`Section gpu <Speed_gpu>` | `Benchmarks <https://lammps.sandia.gov/bench.html>`_ | int |
| :ref:`GPU <PKG-GPU>` | GPU-enabled styles | :doc:`Section gpu <Speed_gpu>` | `Benchmarks <https://www.lammps.org/bench.html>`_ | int |
+----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
| :ref:`GRANULAR <PKG-GRANULAR>` | granular systems | :doc:`Howto granular <Howto_granular>` | pour | no |
+----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
| :ref:`KIM <PKG-KIM>` | OpenKIM wrapper | :doc:`pair_style kim <pair_kim>` | kim | ext |
+----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
| :ref:`KOKKOS <PKG-KOKKOS>` | Kokkos-enabled styles | :doc:`Speed kokkos <Speed_kokkos>` | `Benchmarks <https://lammps.sandia.gov/bench.html>`_ | no |
| :ref:`KOKKOS <PKG-KOKKOS>` | Kokkos-enabled styles | :doc:`Speed kokkos <Speed_kokkos>` | `Benchmarks <https://www.lammps.org/bench.html>`_ | no |
+----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
| :ref:`KSPACE <PKG-KSPACE>` | long-range Coulombic solvers | :doc:`kspace_style <kspace_style>` | peptide | no |
+----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
@ -67,7 +67,7 @@ package:
+----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
| :ref:`MSCG <PKG-MSCG>` | multi-scale coarse-graining wrapper | :doc:`fix mscg <fix_mscg>` | mscg | ext |
+----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
| :ref:`OPT <PKG-OPT>` | optimized pair styles | :doc:`Speed opt <Speed_opt>` | `Benchmarks <https://lammps.sandia.gov/bench.html>`_ | no |
| :ref:`OPT <PKG-OPT>` | optimized pair styles | :doc:`Speed opt <Speed_opt>` | `Benchmarks <https://www.lammps.org/bench.html>`_ | no |
+----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+
| :ref:`PERI <PKG-PERI>` | Peridynamics models | :doc:`pair_style peri <pair_peri>` | peri | no |
+----------------------------------+--------------------------------------+----------------------------------------------------+------------------------------------------------------+---------+

12
doc/src/Packages_user.rst
View File

@ -39,6 +39,8 @@ package:
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-BOCS <PKG-USER-BOCS>` | BOCS bottom up coarse graining | :doc:`fix bocs <fix_bocs>` | USER/bocs | no |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-BROWNIAN <PKG-USER-BROWNIAN>` | Brownian dynamics and self-propelled particles | :doc:`fix brownian <fix_brownian>`, :doc:`fix propel/self <fix_propel_self>` | USER/brownian | no |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-CGDNA <PKG-USER-CGDNA>` | coarse-grained DNA force fields | src/USER-CGDNA/README | USER/cgdna | no |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-CGSDK <PKG-USER-CGSDK>` | SDK coarse-graining model | :doc:`pair_style lj/sdk <pair_sdk>` | USER/cgsdk | no |
@ -57,12 +59,16 @@ package:
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-H5MD <PKG-USER-H5MD>` | dump output via HDF5 | :doc:`dump h5md <dump_h5md>` | n/a | ext |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-INTEL <PKG-USER-INTEL>` | optimized Intel CPU and KNL styles | :doc:`Speed intel <Speed_intel>` | `Benchmarks <https://lammps.sandia.gov/bench.html>`_ | no |
| :ref:`USER-HDNNP <PKG-USER-HDNNP>` | High-dimensional neural network potentials | :doc:`pair_style hdnnp <pair_hdnnp>` | USER/hdnnp | ext |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-INTEL <PKG-USER-INTEL>` | optimized Intel CPU and KNL styles | :doc:`Speed intel <Speed_intel>` | `Benchmarks <https://www.lammps.org/bench.html>`_ | no |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-LB <PKG-USER-LB>` | Lattice Boltzmann fluid | :doc:`fix lb/fluid <fix_lb_fluid>` | USER/lb | no |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-MANIFOLD <PKG-USER-MANIFOLD>` | motion on 2d surfaces | :doc:`fix manifoldforce <fix_manifoldforce>` | USER/manifold | no |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-MDI <PKG-USER-MDI>` | client-server coupling | :doc:`MDI Howto <Howto_mdi>` | USER/mdi | ext |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-MEAMC <PKG-USER-MEAMC>` | modified EAM potential (C++) | :doc:`pair_style meam/c <pair_meamc>` | meamc | no |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-MESODPD <PKG-USER-MESODPD>` | mesoscale DPD models | :doc:`pair_style edpd <pair_mesodpd>` | USER/mesodpd | no |
@ -79,7 +85,7 @@ package:
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-NETCDF <PKG-USER-NETCDF>` | dump output via NetCDF | :doc:`dump netcdf <dump_netcdf>` | n/a | ext |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-OMP <PKG-USER-OMP>` | OpenMP-enabled styles | :doc:`Speed omp <Speed_omp>` | `Benchmarks <https://lammps.sandia.gov/bench.html>`_ | no |
| :ref:`USER-OMP <PKG-USER-OMP>` | OpenMP-enabled styles | :doc:`Speed omp <Speed_omp>` | `Benchmarks <https://www.lammps.org/bench.html>`_ | no |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-PACE <PKG-USER-PACE>` | Fast implementation of Atomic Cluster Expansion (ACE) potential | :doc:`pair pace <pair_pace>` | USER/pace | ext |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
@ -95,6 +101,8 @@ package:
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-QUIP <PKG-USER-QUIP>` | QUIP/libatoms interface | :doc:`pair_style quip <pair_quip>` | USER/quip | ext |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-RANN <PKG-USER-RANN>` | rapid atomistic neural network (RANN) potentials | :doc:`pair rann <pair_rann>` | USER/rann | no |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-REACTION <PKG-USER-REACTION>` | chemical reactions in classical MD | :doc:`fix bond/react <fix_bond_react>` | USER/reaction | no |
+------------------------------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------+------------------------------------------------------+---------+
| :ref:`USER-REAXC <PKG-USER-REAXC>` | ReaxFF potential (C/C++) | :doc:`pair_style reaxc <pair_reaxc>` | reax | no |

8
doc/src/Python_install.rst
View File

@ -377,14 +377,6 @@ make MPI calls directly from Python in your script, if you desire.
We have tested this with `MPI for Python <https://mpi4py.readthedocs.io/>`_
(aka mpi4py) and you will find installation instruction for it below.
.. note::
Older LAMMPS versions were also tested with `PyPar <https://github.com/daleroberts/pypar>`_
but we can no longer test it, since it does not work with the Python
(3.x) versions on our test servers. Since there have been no updates
to PyPar visible in its repository since November 2016 we have to assume
it is no longer maintained.
Installation of mpi4py (version 3.0.3 as of Sep 2020) can be done as
follows:

19
doc/src/Run_options.rst
View File

@ -10,6 +10,7 @@ letter abbreviation can be used:
* :ref:`-i or -in <file>`
* :ref:`-k or -kokkos <run-kokkos>`
* :ref:`-l or -log <log>`
* :ref:`-mdi <mdi>`
* :ref:`-m or -mpicolor <mpicolor>`
* :ref:`-c or -cite <cite>`
* :ref:`-nc or -nocite <nocite>`
@ -196,9 +197,23 @@ Option -plog will override the name of the partition log files file.N.
----------
.. _mdi:
**-mdi 'multiple flags'**
This flag is only recognized and used when LAMMPS has support for the MolSSI
Driver Interface (MDI) included as part of the :ref:`USER-MDI <PKG-USER-MDI>`
package. This flag is specific to the MDI library and controls how LAMMPS
interacts with MDI. There are usually multiple flags that have to follow it
and those have to be placed in quotation marks. For more information about
how to launch LAMMPS in MDI client/server mode please refer to the
:doc:`MDI Howto <Howto_mdi>`.
----------
.. _mpicolor:
**-mpicolor** color
**-mpicolor color**
If used, this must be the first command-line argument after the LAMMPS
executable name. It is only used when LAMMPS is launched by an mpirun
@ -223,7 +238,7 @@ links with from the lib/message directory. See the
.. _cite:
**-cite style or file name**
**-cite style** or **file name**
Select how and where to output a reminder about citing contributions
to the LAMMPS code that were used during the run. Available styles are

2
doc/src/Speed.rst
View File

@ -12,7 +12,7 @@ accelerator packages provided with LAMMPS that contain code optimized
for certain kinds of hardware, including multi-core CPUs, GPUs, and
Intel Xeon Phi co-processors.
The `Benchmark page <https://lammps.sandia.gov/bench.html>`_ of the LAMMPS
The `Benchmark page <https://www.lammps.org/bench.html>`_ of the LAMMPS
web site gives performance results for the various accelerator
packages discussed on the :doc:`Speed packages <Speed_packages>` doc
page, for several of the standard LAMMPS benchmark problems, as a

8
doc/src/Speed_bench.rst
View File

@ -1,7 +1,7 @@
Benchmarks
==========
Current LAMMPS performance is discussed on the `Benchmarks page <https://lammps.sandia.gov/bench.html>`_ of the `LAMMPS website <lws_>`_
Current LAMMPS performance is discussed on the `Benchmarks page <https://www.lammps.org/bench.html>`_ of the `LAMMPS website <lws_>`_
where timings and parallel efficiency are listed. The page has
several sections, which are briefly described below:
@ -43,11 +43,11 @@ to build LAMMPS and run on that kind of hardware.
The bench/POTENTIALS directory has input files which correspond to the
table of results on the
`Potentials <https://lammps.sandia.gov/bench.html#potentials>`_ section of
`Potentials <https://www.lammps.org/bench.html#potentials>`_ section of
the Benchmarks web page. So you can also run those test problems on
your machine.
The `billion-atom <https://lammps.sandia.gov/bench.html#billion>`_ section
The `billion-atom <https://www.lammps.org/bench.html#billion>`_ section
of the Benchmarks web page has performance data for very large
benchmark runs of simple Lennard-Jones (LJ) models, which use the
bench/in.lj input script.
@ -73,4 +73,4 @@ estimate parallel performance for multi-node runs using the same logic
as for all-MPI mode, except that now you will typically need many more
atoms/node to achieve good scalability.
.. _lws: https://lammps.sandia.gov
.. _lws: https://www.lammps.org

2
doc/src/Speed_gpu.rst
View File

@ -152,7 +152,7 @@ in OpenCL mode on CPUs (which uses vectorization and multithreading) is
usually resulting in inferior performance compared to using LAMMPS' native
threading and vectorization support in the USER-OMP and USER-INTEL packages.
See the `Benchmark page <https://lammps.sandia.gov/bench.html>`_ of the
See the `Benchmark page <https://www.lammps.org/bench.html>`_ of the
LAMMPS web site for performance of the GPU package on various
hardware, including the Titan HPC platform at ORNL.

2
doc/src/Speed_kokkos.rst
View File

@ -406,7 +406,7 @@ Generally speaking, the following rules of thumb apply:
package also can increase the vector length of vector instructions
by switching to single or mixed precision mode.
See the `Benchmark page <https://lammps.sandia.gov/bench.html>`_ of the
See the `Benchmark page <https://www.lammps.org/bench.html>`_ of the
LAMMPS web site for performance of the KOKKOS package on different
hardware.

2
doc/src/Speed_packages.rst
View File

@ -145,7 +145,7 @@ sub-directories with Make.py commands and input scripts for using all
the accelerator packages on various machines. See the README files in
those directories.
As mentioned above, the `Benchmark page <https://lammps.sandia.gov/bench.html>`_ of the LAMMPS web site gives
As mentioned above, the `Benchmark page <https://www.lammps.org/bench.html>`_ of the LAMMPS web site gives
performance results for the various accelerator packages for several
of the standard LAMMPS benchmark problems, as a function of problem
size and number of compute nodes, on different hardware platforms.

104
doc/src/Tools.rst
View File

@ -6,15 +6,15 @@ molecular dynamics computations. Additional pre- and post-processing
steps are often necessary to setup and analyze a simulation. A list
of such tools can be found on the `LAMMPS webpage <lws_>`_ at these links:
* `Pre/Post processing <https://lammps.sandia.gov/prepost.html>`_
* `Offsite LAMMPS packages & tools <https://lammps.sandia.gov/offsite.html>`_
* `Pre/Post processing <https://www.lammps.org/prepost.html>`_
* `Offsite LAMMPS packages & tools <https://www.lammps.org/offsite.html>`_
* `Pizza.py toolkit <pizza_>`_
The last link for `Pizza.py <pizza_>`_ is a Python-based tool developed at
Sandia which provides tools for doing setup, analysis, plotting, and
visualization for LAMMPS simulations.
.. _lws: https://lammps.sandia.gov
.. _lws: https://www.lammps.org
.. _pizza: https://pizza.sandia.gov
.. _python: https://www.python.org
@ -94,6 +94,7 @@ Miscellaneous tools
* :ref:`kate <kate>`
* :ref:`LAMMPS shell <lammps_shell>`
* :ref:`LAMMPS magic patterns for file(1) <magic>`
* :ref:`Offline build tool <offline>`
* :ref:`singularity <singularity_tool>`
* :ref:`SWIG interface <swig>`
* :ref:`vim <vim>`
@ -756,6 +757,103 @@ See the README file in the tools/msi2lmp folder for more information.
----------
.. _offline:
Scripts for building LAMMPS when offline
----------------------------------------
In some situations it might be necessary to build LAMMPS on a system
without direct internet access. The scripts in ``tools/offline`` folder
allow you to pre-load external dependencies for both the documentation
build and for building LAMMPS with CMake.
It does so by
#. downloading necessary ``pip`` packages,
#. cloning ``git`` repositories
#. downloading tarballs
to a designated cache folder.
As of April 2021, all of these downloads make up around 600MB. By
default, the offline scripts will download everything into the
``$HOME/.cache/lammps`` folder, but this can be changed by setting the
``LAMMPS_CACHING_DIR`` environment variable.
Once the caches have been initialized, they can be used for building the
LAMMPS documentation or compiling LAMMPS using CMake on an offline
system.
The ``use_caches.sh`` script must be sourced into the current shell
to initialize the offline build environment. Note that it must use
the same ``LAMMPS_CACHING_DIR``. This script does the following:
#. Set up environment variables that modify the behavior of both,
``pip`` and ``git``
#. Start a simple local HTTP server using Python to host files for CMake
Afterwards, it will print out instruction on how to modify the CMake
command line to make sure it uses the local HTTP server.
To undo the environment changes and shutdown the local HTTP server,
run the ``deactivate_caches`` command.
Examples
^^^^^^^^
For all of the examples below, you first need to create the cache, which
requires an internet connection.
.. code-block:: bash
./tools/offline/init_caches.sh
Afterwards, you can disconnect or copy the contents of the
``LAMMPS_CACHING_DIR`` folder to an offline system.
Documentation Build
^^^^^^^^^^^^^^^^^^^
The documentation build will create a new virtual environment that
typically first installs dependencies from ``pip``. With the offline
environment loaded, these installations will instead grab the necessary
packages from your local cache.
.. code-block:: bash
# if LAMMPS_CACHING_DIR is different from default, make sure to set it first
# export LAMMPS_CACHING_DIR=path/to/folder
source tools/offline/use_caches.sh
cd doc/
make html
deactivate_caches
CMake Build
^^^^^^^^^^^
When compiling certain packages with external dependencies, the CMake
build system will download necessary files or sources from the web. For
more flexibility the CMake configuration allows users to specify the URL
of each of these dependencies. What the ``init_caches.sh`` script does
is create a CMake "preset" file, which sets the URLs for all of the known
dependencies and redirects the download to the local cache.
.. code-block:: bash
# if LAMMPS_CACHING_DIR is different from default, make sure to set it first
# export LAMMPS_CACHING_DIR=path/to/folder
source tools/offline/use_caches.sh
mkdir build
cd build
cmake -D LAMMPS_DOWNLOADS_URL=${HTTP_CACHE_URL} -C "${LAMMPS_HTTP_CACHE_CONFIG}" -C ../cmake/presets/most.cmake ../cmake
make -j 8
deactivate_caches
----------
.. _phonon:
phonon tool

1
doc/src/angle_table.rst
View File

@ -69,7 +69,6 @@ parenthesized comments):
HAM (keyword is the first text on line)
N 181 FP 0 0 EQ 90.0 (N, FP, EQ parameters)
(blank line)
N 181 FP 0 0 (N, FP parameters)
1 0.0 200.5 2.5 (index, angle, energy, derivative)
2 1.0 198.0 2.5
...

2
doc/src/atom_modify.rst
View File

@ -80,7 +80,7 @@ LAMMPS commands require a map, even for atomic systems, and will
generate an error if one does not exist. The *map* keyword thus
allows you to force the creation of a map. The *yes* value will
create either an *array* or *hash* style map, as explained in the next
paragraph. The *array* and *hash* values create an atom-style or
paragraph. The *array* and *hash* values create an array-style or
hash-style map respectively.
For an *array*\ -style map, each processor stores a lookup table of

4
doc/src/balance.rst
View File

@ -257,7 +257,7 @@ factor, similar to how the :doc:`fix balance shift <fix_balance>`
command operates.
The *dimstr* argument is a string of characters, each of which must be
an "x" or "y" or "z". Eacn character can appear zero or one time,
an "x" or "y" or "z". Each character can appear zero or one time,
since there is no advantage to balancing on a dimension more than
once. You should normally only list dimensions where you expect there
to be a density variation in the particles.
@ -285,7 +285,7 @@ plane gets closer to the target value.
After the balanced plane positions are determined, if any pair of
adjacent planes are closer together than the neighbor skin distance
(as specified by the :doc`neigh_modify <neigh_modify>` command), then
(as specified by the :doc:`neigh_modify <neigh_modify>` command), then
the plane positions are shifted to separate them by at least this
amount. This is to prevent particles being lost when dynamics are run
with processor sub-domains that are too narrow in one or more

58
doc/src/comm_modify.rst
View File

@ -11,13 +11,17 @@ Syntax
comm_modify keyword value ...
* zero or more keyword/value pairs may be appended
* keyword = *mode* or *cutoff* or *cutoff/multi* or *group* or *vel*
* keyword = *mode* or *cutoff* or *cutoff/multi* or *multi/reduce* or *group* or *vel*
.. parsed-literal::
*mode* value = *single* or *multi* = communicate atoms within a single or multiple distances
*mode* value = *single*, *multi*, or *multi/old* = communicate atoms within a single or multiple distances
*cutoff* value = Rcut (distance units) = communicate atoms from this far away
*cutoff/multi* type value
*cutoff/multi* collection value
collection = atom collection or collection range (supports asterisk notation)
value = Rcut (distance units) = communicate atoms for selected types from this far away
*reduce/multi* arg = none = reduce number of communicated ghost atoms for multi style
*cutoff/multi/old* type value
type = atom type or type range (supports asterisk notation)
value = Rcut (distance units) = communicate atoms for selected types from this far away
*group* value = group-ID = only communicate atoms in the group
@ -28,9 +32,9 @@ Examples
.. code-block:: LAMMPS
comm_modify mode multi
comm_modify mode multi reduce/multi
comm_modify mode multi group solvent
comm_modift mode multi cutoff/multi 1 10.0 cutoff/multi 2*4 15.0
comm_modify mode multi cutoff/multi 1 10.0 cutoff/multi 2*4 15.0
comm_modify vel yes
comm_modify mode single cutoff 5.0 vel yes
comm_modify cutoff/multi * 0.0
@ -62,12 +66,18 @@ sub-domain. The distance is by default the maximum of the neighbor
cutoff across all atom type pairs.
For many systems this is an efficient algorithm, but for systems with
widely varying cutoffs for different type pairs, the *multi* mode can
be faster. In this case, each atom type is assigned its own distance
widely varying cutoffs for different type pairs, the *multi* or *multi/old* mode can
be faster. In *multi*, each atom is assigned to a collection which should
correspond to a set of atoms with similar interaction cutoffs.
In this case, each atom collection is assigned its own distance
cutoff for communication purposes, and fewer atoms will be
communicated. See the :doc:`neighbor multi <neighbor>` command for a
neighbor list construction option that may also be beneficial for
simulations of this kind.
communicated. in *multi/old*, a similar technique is used but atoms
are grouped by atom type. See the :doc:`neighbor multi <neighbor>` and
:doc:`neighbor multi/old <neighbor>` commands for
neighbor list construction options that may also be beneficial for
simulations of this kind. The *multi* communication mode is only compatible
with the *multi* neighbor style. The *multi/old* communication mode is comparable
with both the *multi* and *multi/old* neighbor styles.
The *cutoff* keyword allows you to extend the ghost cutoff distance
for communication mode *single*\ , which is the distance from the borders
@ -87,12 +97,26 @@ warning is printed, if this bond based estimate is larger than the
communication cutoff used.
The *cutoff/multi* option is equivalent to *cutoff*\ , but applies to
communication mode *multi* instead. Since in this case the communication
cutoffs are determined per atom type, a type specifier is needed and
cutoff for one or multiple types can be extended. Also ranges of types
using the usual asterisk notation can be given. For granular pair styles,
the default cutoff is set to the sum of the current maximum atomic radii
for each type.
communication mode *multi* instead. Since the communication cutoffs are
determined per atom collections, a collection specifier is needed and
cutoff for one or multiple collections can be extended. Also ranges of
collections using the usual asterisk notation can be given. Collections
are indexed from 1 to N where N is the total number of collections.
Note that the arguments for *cutoff/multi* are parsed right before each
simulation to account for potential changes in the number of
collections. Custom cutoffs are preserved between runs but if
collections are redefined, one may want to re-specify the communication
cutoffs. For granular pair styles,the default cutoff is set to the sum
of the current maximum atomic radii for each collection. The
*cutoff/multi/old* option is similar to *cutoff/multi* except it
operates on atom types as opposed to collections.
The *reduce/multi* option applies to *multi* and sets the communication
cutoff for a particle equal to the maximum interaction distance between particles
in the same collection. This reduces the number of
ghost atoms that need to be communicated. This method is only compatible with the
*multi* neighbor style and requires a half neighbor list and Newton on.
See the :doc:`neighbor multi <neighbor>` command for more information.
These are simulation scenarios in which it may be useful or even
necessary to set a ghost cutoff > neighbor cutoff:
@ -123,7 +147,7 @@ ghost cutoff should be set.
In the last scenario, a :doc:`fix <fix>` or :doc:`compute <compute>` or
:doc:`pairwise potential <pair_style>` needs to calculate with ghost
atoms beyond the normal pairwise cutoff for some computation it
performs (e.g. locate neighbors of ghost atoms in a multibody pair
performs (e.g. locate neighbors of ghost atoms in a manybody pair
potential). Setting the ghost cutoff appropriately can insure it will
find the needed atoms.

1
doc/src/commands_list.rst
View File

@ -59,6 +59,7 @@ Commands
lattice
log
mass
mdi_engine
message
min_modify
min_spin

2
doc/src/compute_fep.rst
View File

@ -48,6 +48,8 @@ Examples
compute 1 all fep 298 pair lj/cut epsilon 1 * v_delta pair lj/cut sigma 1 * v_delta volume yes
compute 1 all fep 300 atom charge 2 v_delta
Example input scripts available: examples/USER/fep
Description
"""""""""""

2
doc/src/compute_temp_drude.rst
View File

@ -20,6 +20,8 @@ Examples
compute TDRUDE all temp/drude
Example input scripts available: examples/USER/drude
Description
"""""""""""

4
doc/src/fix.rst
View File

@ -182,6 +182,9 @@ accelerated styles exist.
* :doc:`ave/time <fix_ave_time>` - compute/output global time-averaged quantities
* :doc:`aveforce <fix_aveforce>` - add an averaged force to each atom
* :doc:`balance <fix_balance>` - perform dynamic load-balancing
* :doc:`brownian <fix_brownian>` - overdamped translational brownian motion
* :doc:`brownian/asphere <fix_brownian>` - overdamped translational and rotational brownian motion for ellipsoids
* :doc:`brownian/sphere <fix_brownian>` - overdamped translational and rotational brownian motion for spheres
* :doc:`bocs <fix_bocs>` - NPT style time integration with pressure correction
* :doc:`bond/break <fix_bond_break>` - break bonds on the fly
* :doc:`bond/create <fix_bond_create>` - create bonds on the fly
@ -241,6 +244,7 @@ accelerated styles exist.
* :doc:`lb/viscous <fix_lb_viscous>` -
* :doc:`lineforce <fix_lineforce>` - constrain atoms to move in a line
* :doc:`manifoldforce <fix_manifoldforce>` - restrain atoms to a manifold during minimization
* :doc:`mdi/engine <fix_mdi_engine>` - connect LAMMPS to external programs via the MolSSI Driver Interface (MDI)
* :doc:`meso/move <fix_meso_move>` - move mesoscopic SPH/SDPD particles in a prescribed fashion
* :doc:`momentum <fix_momentum>` - zero the linear and/or angular momentum of a group of atoms
* :doc:`momentum/chunk <fix_momentum>` - zero the linear and/or angular momentum of a chunk of atoms

3
doc/src/fix_adapt_fep.rst
View File

@ -56,6 +56,9 @@ Examples
fix 1 all adapt/fep 1 pair lj/cut epsilon * * v_scale1 coul/cut scale 3 3 v_scale2 scale yes reset yes
fix 1 all adapt/fep 10 atom diameter 1 v_size
Example input scripts available: examples/USER/fep
Description
"""""""""""

2
doc/src/fix_balance.rst
View File

@ -216,7 +216,7 @@ above. It changes the positions of cutting planes between processors
in an iterative fashion, seeking to reduce the imbalance factor.
The *dimstr* argument is a string of characters, each of which must be
an "x" or "y" or "z". Eacn character can appear zero or one time,
an "x" or "y" or "z". Each character can appear zero or one time,
since there is no advantage to balancing on a dimension more than
once. You should normally only list dimensions where you expect there
to be a density variation in the particles.

45
doc/src/fix_bond_react.rst
View File

@ -17,7 +17,7 @@ Syntax
* ID, group-ID are documented in :doc:`fix <fix>` command.
* bond/react = style name of this fix command
* the common keyword/values may be appended directly after 'bond/react'
* this applies to all reaction specifications (below)
* common keywords apply to all reaction specifications
* common_keyword = *stabilization* or *reset_mol_ids*
.. parsed-literal::
@ -328,8 +328,8 @@ keyword 'ChiralIDs' lists the atom IDs of chiral atoms whose
handedness should be enforced. The fifth optional section begins with
the keyword 'Constraints' and lists additional criteria that must be
satisfied in order for the reaction to occur. Currently, there are
five types of constraints available, as discussed below: 'distance',
'angle', 'dihedral', 'arrhenius', and 'rmsd'.
six types of constraints available, as discussed below: 'distance',
'angle', 'dihedral', 'arrhenius', 'rmsd', and 'custom'.
A sample map file is given below:
@ -500,6 +500,45 @@ example, the molecule fragment could consist of only the backbone
atoms of a polymer chain. This constraint can be used to enforce a
specific relative position and orientation between reacting molecules.
The constraint of type 'custom' has the following syntax:
.. parsed-literal::
custom *varstring*
where 'custom' is the required keyword, and *varstring* is a
variable expression. The expression must be a valid equal-style
variable formula that can be read by the :doc:`variable <variable>` command,
after any special reaction functions are evaluated. If the resulting
expression is zero, the reaction is prevented from occurring;
otherwise, it is permitted to occur. There are two special reaction
functions available, 'rxnsum' and 'rxnave'. These functions operate
over the atoms in a given reaction site, and have one mandatory
argument and one optional argument. The mandatory argument is the
identifier for an atom-style variable. The second, optional argument
is the name of a molecule fragment in the pre-reaction template, and
can be used to operate over a subset of atoms in the reaction site.
The 'rxnsum' function sums the atom-style variable over the reaction
site, while the 'rxnave' returns the average value. For example, a
constraint on the total potential energy of atoms involved in the
reaction can be imposed as follows:
.. code-block:: LAMMPS
compute 1 all pe/atom # in LAMMPS input script
variable my_pe atom c_1 # in LAMMPS input script
.. code-block:: LAMMPS
custom "rxnsum(v_my_pe) > 100" # in Constraints section of map file
The above example prevents the reaction from occurring unless the
total potential energy of the reaction site is above 100. The variable
expression can be interpreted as the probability of the reaction
occurring by using an inequality and the 'random(x,y,z)' function
available as an equal-style variable input, similar to the 'arrhenius'
constraint above.
By default, all constraints must be satisfied for the reaction to
occur. In other words, constraints are evaluated as a series of
logical values using the logical AND operator "&&". More complex logic

216
doc/src/fix_brownian.rst Normal file
View File

@ -0,0 +1,216 @@
.. index:: fix brownian
.. index:: fix brownian/sphere
.. index:: fix brownian/asphere
fix brownian command
===========================
fix brownian/sphere command
===========================
fix brownian/sphere command
===========================
Syntax
""""""
.. parsed-literal::
fix ID group-ID style_name temp seed keyword args
* ID, group-ID are documented in :doc:`fix <fix>` command
* style_name = *brownian* or *brownian/sphere* or *brownian/asphere*
* temp = temperature
* seed = random number generator seed
* one or more keyword/value pairs may be appended
* keyword = *rng* or *dipole* or *gamma_r_eigen* or *gamma_t_eigen* or *gamma_r* or *gamma_t*
.. parsed-literal::
*rng* value = *uniform* or *gaussian* or *none*
*uniform* = use uniform random number generator
*gaussian* = use gaussian random number generator
*none* = turn off noise
*dipole* value = *mux* and *muy* and *muz* for *brownian/asphere*
*mux*, *muy*, and *muz* = update orientation of dipole having direction (*mux*,*muy*,*muz*) in body frame of rigid body
*gamma_r_eigen* values = *gr1* and *gr2* and *gr3* for *brownian/asphere*
*gr1*, *gr2*, and *gr3* = diagonal entries of body frame rotational friction tensor
*gamma_r* values = *gr* for *brownian/sphere*
*gr* = magnitude of the (isotropic) rotational friction tensor
*gamma_t_eigen* values = *gt1* and *gt2* and *gt3* for *brownian/asphere*
*gt1*, *gt2*, and *gt3* = diagonal entries of body frame translational friction tensor
*gamma_t* values = *gt* for *brownian* and *brownian/sphere*
*gt* = magnitude of the (isotropic) translational friction tensor
Examples
""""""""
.. code-block:: LAMMPS
fix 1 all brownian 1.0 12908410 gamma_t 1.0
fix 1 all brownian 1.0 12908410 gamma_t 3.0 rng gaussian
fix 1 all brownian/sphere 1.0 1294019 gamma_t 3.0 gamma_r 1.0
fix 1 all brownian/sphere 1.0 19581092 gamma_t 1.0 gamma_r 0.3 rng none
fix 1 all brownian/asphere 1.0 1294019 gamma_t_eigen 1.0 2.0 3.0 gamma_r_eigen 4.0 7.0 8.0 rng gaussian
fix 1 all brownian/asphere 1.0 1294019 gamma_t_eigen 1.0 2.0 3.0 gamma_r_eigen 4.0 7.0 8.0 dipole 1.0 0.0 0.0
Description
"""""""""""
Perform Brownian Dynamics time integration to update position, velocity,
dipole orientation (for spheres) and quaternion orientation (for
ellipsoids, with optional dipole update as well) of all particles in the
fix group in each timestep. Brownian Dynamics uses Newton's laws of
motion in the limit that inertial forces are negligible compared to
viscous forces. The stochastic equation of motion for the center of mass
positions is
.. math::
d\mathbf{r} = \mathbf{\gamma}_t^{-1}\mathbf{F}dt+\sqrt{2k_BT}\mathbf{\gamma}_t^{-1/2}d\mathbf{W}_t,
in the lab-frame (i.e. :math:`\mathbf{\gamma}_t` is not diagonal, but
only depends on orientation and so the noise is still additive).
The rotational motion for the spherical and ellipsoidal particles is not
as simple an expression, but is chosen to replicate the Boltzmann
distribution for the case of conservative torques (see :ref:`(Ilie)
<Ilie1>` or :ref:`(Delong) <Delong1>`).
For the style *brownian*, only the positions of the particles are
updated. This is therefore suitable for point particle simulations.
For the style *brownian/sphere*, the positions of the particles are
updated, and a dipole slaved to the spherical orientation is also
updated. This style therefore requires the hybrid atom style
:doc:`atom_style dipole <atom_style>` and :doc:`atom_style sphere
<atom_style>`.
For the style *brownian/asphere*, the center of mass positions and the
quaternions of ellipsoidal particles are updated. This fix style is
suitable for equations of motion where the rotational and translational
friction tensors can be diagonalized in a certain (body) reference frame.
---------
.. note::
This integrator does not by default assume a relationship between the
rotational and translational friction tensors, though such a relationship
should exist in the case of no-slip boundary conditions between the particles and
the surrounding (implicit) solvent. E.g. in the case of spherical particles,
the condition :math:`\gamma_t=3\gamma_r/\sigma^2` must be explicitly
accounted for by setting *gamma_t* to 3x and *gamma_r* to x (where
:math:`\sigma` is the spherical diameter). A similar (though more complex)
relationship holds for ellipsoids and rod-like particles.
---------
.. note::
Temperature computation using the :doc:`compute temp <compute_temp>`
will not correctly compute temperature of these overdamped dynamics
since we are explicitly neglecting inertial effects.
Furthermore, this time integrator does not add the stochastic terms or
viscous terms to the force and/or torques. Rather, they are just added
in to the equations of motion to update the degrees of freedom.
---------
If the *rng* keyword is used with the *uniform* value, then the noise
is generated from a uniform distribution (see
:ref:`(Dunweg) <Dunweg7>` for why this works). This is the same method
of noise generation as used in :doc:`fix_langevin <fix_langevin>`.
If the *rng* keyword is used with the *gaussian* value, then the noise
is generated from a gaussian distribution. Typically this added
complexity is unnecessary, and one should be fine using the *uniform*
value for reasons argued in :ref:`(Dunweg) <Dunweg7>`.
If the *rng* keyword is used with the *none* value, then the noise
terms are set to zero.
The *gamma_t* keyword sets the (isotropic) translational viscous damping.
Required for (and only compatible with) *brownian* and *brownian/sphere*.
The units of *gamma_t* are mass/time.
The *gamma_r* keyword sets the (isotropic) rotational viscous damping.
Required for (and only compatible with) *brownian/sphere*.
The units of *gamma_r* are mass*length**2/time.
The *gamma_r_eigen*, and *gamma_t_eigen* keywords are the eigenvalues of
the rotational and viscous damping tensors (having the same units as
their isotropic counterparts). Required for (and only compatible with)
*brownian/asphere*. For a 2D system, the first two values of *gamma_r_eigen*
must be inf (only rotation in xy plane), and the third value of *gamma_t_eigen*
must be inf (only diffusion in xy plane).
If the *dipole* keyword is used, then the dipole moments of the particles
are updated as described above. Only compatible with *brownian/asphere*
(as *brownian/sphere* updates dipoles automatically).
----------
.. note::
For style *brownian/asphere*, the components *gamma_t_eigen* =(x,x,x) and
*gamma_r_eigen* = (y,y,y), the dynamics will replicate those of the
*brownian/sphere* style with *gamma_t* = x and *gamma_r* = y.
----------
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
No information about this fix is written to :doc:`binary restart files <restart>`.
No global or per-atom quantities are stored
by this fix for access by various :doc:`output commands <Howto_output>`.
No parameter of this fix can be used with the *start/stop* keywords of
the :doc:`run <run>` command. This fix is not invoked during
:doc:`energy minimization <minimize>`.
Restrictions
""""""""""""
The style *brownian/sphere* fix requires that atoms store torque and angular velocity (omega)
as defined by the :doc:`atom_style sphere <atom_style>` command.
The style *brownian/asphere* fix requires that atoms store torque and quaternions
as defined by the :doc:`atom_style ellipsoid <atom_style>` command.
If the *dipole* keyword is used, they must also store a dipole moment
as defined by the :doc:`atom_style dipole <atom_style>` command.
This fix is part of the USER-BROWNIAN package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package <Build_package>`
doc page for more info.
Related commands
""""""""""""""""
:doc:`fix propel/self <fix_propel_self>`,
:doc:`fix langevin <fix_langevin>`, :doc:`fix nve/sphere <fix_nve_sphere>`,
Default
"""""""
The default for *rng* is *uniform*. The default for the rotational and translational friction
tensors are the identity tensor.
----------
.. _Ilie1:
**(Ilie)** Ilie, Briels, den Otter, Journal of Chemical Physics, 142, 114103 (2015).
.. _Delong1:
**(Delong)** Delong, Usabiaga, Donev, Journal of Chemical Physics. 143, 144107 (2015)
.. _Dunweg7:
**(Dunweg)** Dunweg and Paul, Int J of Modern Physics C, 2, 817-27 (1991).

2
doc/src/fix_drude.rst
View File

@ -22,6 +22,8 @@ Examples
fix 1 all drude 1 1 0 1 0 2 2 2
fix 1 all drude C C N C N D D D
Example input scripts available: examples/USER/drude
Description
"""""""""""

2
doc/src/fix_drude_transform.rst
View File

@ -25,6 +25,8 @@ Examples
fix 3 all drude/transform/direct
fix 1 all drude/transform/inverse
Example input scripts available: examples/USER/drude
Description
"""""""""""

5
doc/src/fix_grem.rst
View File

@ -92,6 +92,11 @@ The :doc:`thermo_modify <thermo_modify>` *press* option is supported
by this fix to add the rescaled kinetic pressure as part of
:doc:`thermodynamic output <thermo_style>`.
This fix computes a global scalar which can be accessed by various
:doc:`output commands <Howto_output>`. The scalar is the effective
temperature :math:`T_{eff}`. The scalar value calculated by this
fix is "intensive".
Restrictions
""""""""""""

2
doc/src/fix_langevin_drude.rst
View File

@ -35,6 +35,8 @@ Examples
fix 3 all langevin/drude 300.0 100.0 19377 1.0 20.0 83451
fix 1 all langevin/drude 298.15 100.0 19377 5.0 10.0 83451 zero yes
Example input scripts available: examples/USER/drude
Description
"""""""""""

59
doc/src/fix_mdi_engine.rst Normal file
View File

@ -0,0 +1,59 @@
.. index:: fix mdi/engine
fix mdi/engine command
======================
Syntax
""""""
.. parsed-literal::
fix ID group-ID mdi/engine
* ID, group-ID are documented in :doc:`fix <fix>` command
* mdi/engine = style name of this fix command
Examples
""""""""
.. code-block:: LAMMPS
fix 1 all mdi/engine
Description
"""""""""""
This fix is used along with the :doc:`mdi/engine <mdi_engine>` command
to enable LAMMPS to use the `MDI Library
<https://molssi-mdi.github.io/MDI_Library/html/index.html>`_ to run as
an MDI engine. The fix provides hooks that enable MDI driver codes to
communicate with LAMMPS at various points within a LAMMPS timestep.
It is not generally necessary to add this fix to a LAMMPS input file,
even when using the :doc:`mdi/engine <mdi_engine>` command. If the
:doc:`mdi/engine <mdi_engine>` command is executed and this fix is not
present, it will automatically be added and applied as a new fix for
all atoms for the duration of the command. Thus it is only necessary
to add this fix to an input file when you want to modify the group-ID
or the ordering of this fix relative to other fixes in the input script.
For more information about running LAMMPS as an MDI engine, see the
:doc:`mdi/engine <mdi_engine>` command and the :doc:`Howto mdi
<Howto_mdi>` doc page.
Restrictions
""""""""""""
This command is part of the USER-MDI package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` doc page for more info.
Related commands
""""""""""""""""
:doc:`mdi/engine <mdi_engine>`
Default
"""""""
none

34
doc/src/fix_precession_spin.rst
View File

@ -12,7 +12,7 @@ Syntax
* ID, group are documented in :doc:`fix <fix>` command
* precession/spin = style name of this fix command
* style = *zeeman* or *anisotropy* or *cubic*
* style = *zeeman* or *anisotropy* or *cubic* or *stt*
.. parsed-literal::
@ -22,12 +22,12 @@ Syntax
*anisotropy* args = K x y z
K = intensity of the magnetic anisotropy (in eV)
x y z = vector direction of the anisotropy
.. parsed-literal::
*cubic* args = K1 K2c n1x n1y n1x n2x n2y n2z n3x n3y n3z
K1 and K2c = intensity of the magnetic anisotropy (in eV)
n1x to n3z = three direction vectors of the cubic anisotropy
*stt* args = J x y z
J = intensity of the spin-transfer torque field
x y z = vector direction of the field
Examples
""""""""
@ -125,6 +125,11 @@ axis along the :math:`(1 1 1)`-type cube diagonals). :math:`K_2^c >
diagonals. See chapter 2 of :ref:`(Skomski) <Skomski1>` for more
details on cubic anisotropies.
Style *stt* is used to simulate the interaction between the spins and
a spin-transfer torque.
See equation (7) of :ref:`(Chirac) <Chirac1>` for more details about the
implemented spin-transfer torque term.
In all cases, the choice of :math:`(x y z)` only imposes the vector
directions for the forces. Only the direction of the vector is
important; its length is ignored (the entered vectors are
@ -132,6 +137,16 @@ normalized).
Those styles can be combined within one single command line.
.. note::
The norm of all vectors defined with the precession/spin command
have to be non-zero. For example, defining
"fix 1 all precession/spin zeeman 0.1 0.0 0.0 0.0" would result
in an error message.
Since those vector components are used to compute the inverse of the
field (or anisotropy) vector norm, setting a zero-vector would result
in a division by zero.
----------
Restart, fix_modify, output, run start/stop, minimize info
@ -162,11 +177,6 @@ is only enabled if LAMMPS was built with this package, and if the
atom_style "spin" was declared. See the :doc:`Build package
<Build_package>` doc page for more info.
The *precession/spin* style can only be declared once. If more than
one precession type (for example combining an anisotropy and a Zeeman
interactions) has to be declared, they have to be chained in the same
command line (as shown in the examples above).
Related commands
""""""""""""""""
@ -184,3 +194,9 @@ none
**(Skomski)** Skomski, R. (2008). Simple models of magnetism.
Oxford University Press.
.. _Chirac1:
**(Chirac)** Chirac, Theophile, et al. Ultrafast antiferromagnetic
switching in NiO induced by spin transfer torques.
Physical Review B 102.13 (2020): 134415.

183
doc/src/fix_propel_self.rst
View File

@ -8,52 +8,121 @@ Syntax
.. parsed-literal::
fix ID group-ID propel/self mode magnitude keyword values ...
fix ID group-ID propel/self mode magnitude keyword values
* ID, group-ID are documented in :doc:`fix <fix>` command
* propel/self = style name of this fix command
* mode = velocity or quat
* magnitude = magnitude of the active force
* one or more keyword/value pairs may be appended to args
* keyword = *types*
* mode = *dipole* or *velocity* or *quat*
* magnitude = magnitude of self-propulsion force
* zero or one keyword/value pairs may be appended
* keyword = *qvector*
.. parsed-literal::
*qvector* value = direction of force in ellipsoid frame
*sx*, *sy*, *sz* = components of *qvector*
*types* values = one or more atom types
Examples
""""""""
.. code-block:: LAMMPS
fix active_group all propel/self velocity 1.0
fix constant_velocity all viscous 1.0
fix active_group all propel/self quat 1.0
fix active all propel/self quat 1.0 types 1 2 4
fix active all propel/self dipole 40.0
fix active all propel/self velocity 10.0
fix active all propel/self quat 15.7 qvector 1.0 0.0 0.0
Description
"""""""""""
Adds a force of a constant magnitude to each atom in the group. The nature in
which the force is added depends on the mode.
Add a force to each atom in the group due to a self-propulsion force. The
force is given by
For *mode* = *velocity*, the active force acts along the velocity vector of
each atom. This can be interpreted as a velocity-dependent friction,
such as proposed by :ref:`(Erdmann) <Erdmann>`.
.. math::
For *mode* = *quat* the force is applied along the axis obtained
by rotating the x-axis along the atom's quaternion. In other words, the
force is along the x-axis in the atom's body frame. This mode requires
all atoms in the group to have a quaternion, so atom_style should
either be ellipsoid or body. In combination with Langevin thermostat
for translation and rotation in the overdamped regime, the quaternion
mode corresponds to the active Brownian particle model introduced by
:ref:`(Henkes) <Henkes>`, :ref:`(Bialke) <Bialke>` and :ref:`(Fily)
<Fily>`.
F_i = f_P e_i
By default, this fix is applied to all atoms in the group. You can
override this behavior by specifying the atom types the fix should work
on through the *types* keyword.
where *i* is the particle the force is being applied to, :math:`f_P`
is the magnitude of the force, and :math:`e_i` is the vector direction
of the force. The specification of :math:`e_i` is based on which of the
three keywords (*dipole* or *velocity* or *quat*) one selects.
For mode *dipole*, :math:`e_i` is just equal to
the dipole vectors of the atoms in the group. Therefore, if the dipoles
are not unit vectors, the :math:`e_i` will not be unit vectors.
.. note::
If another command changes the magnitude of the dipole, this force will
change accordingly (since :math:`|e_i|` will change, which is physically
equivalent to re-scaling :math:`f_P` while keeping :math:`|e_i|` constant),
and no warning will be provided by LAMMPS. This is almost never what you
want, so ensure you are not changing dipole magnitudes with another LAMMPS
fix or pair style. Furthermore, self-propulsion forces (almost) always
set :math:`e_i` to be a unit vector for all times, so it's best to set
all the dipole magnitudes to 1.0 unless you have a good reason not to
(see the :doc:`set <set>` command on how to do this).
For mode *velocity*, :math:`e_i` points in the direction
of the current velocity (a unit-vector). This can be interpreted as a
velocity-dependent friction, as proposed by e.g. :ref:`(Erdmann) <Erdmann1>`.
For mode *quat*, :math:`e_i` points in the direction of a unit
vector, oriented in the coordinate frame of the ellipsoidal particles,
which defaults to point along the x-direction. This default behavior
can be changed by via the *quatvec* keyword.
The optional *quatvec* keyword specifies the direction of self-propulsion
via a unit vector (sx,sy,sz). The arguments *sx*, *sy*, and *sz*, are
defined within the coordinate frame of the atom's
ellipsoid. For instance, for an ellipsoid with long axis along
its x-direction, if one wanted the self-propulsion force to also
be along this axis, set *sx* equal to 1 and *sy*, *sz* both equal
to zero. This keyword may only be specified for mode *quat*.
.. note::
In using keyword *quatvec*, the three arguments *sx*,
*sy*, and *sz* will be automatically normalized to components
of a unit vector internally to avoid users having to explicitly
do so themselves. Therefore, in mode *quat*, the vectors :math:`e_i`
will always be of unit length.
Along with adding a force contribution, this fix can also
contribute to the virial (pressure) of the system, defined as
:math:`f_P \sum_i <e_i . r_i>/(d V)`, where :math:`r_i` is the
*unwrapped* coordinate of particle i in the case of periodic
boundary conditions. See :ref:`(Winkler) <Winkler1>` for a
discussion of this active pressure contribution.
For modes *dipole* and *quat*, this fix is by default
included in pressure computations.
For mode *velocity*, this fix is by default not included
in pressure computations.
.. note::
In contrast to equilibrium systems, pressure of active systems
in general depends on the geometry of the container.
The active pressure contribution as calculated in this fix
is only valid for certain boundary conditions (spherical
walls, rectangular walls, or periodic boundary conditions).
For other geometries, the pressure must be measured via
explicit calculation of the force per unit area on a wall,
and so one must not calculate it using this fix.
(Use :doc:`fix_modify <fix_modify>` as described below
to turn off the virial contribution of this fix). Again,
see :ref:`(Winkler) <Winkler1>` for discussion of why this
is the case.
Furthermore, when dealing with active systems, the temperature
is no longer well defined. Therefore, one should ensure that
the *virial* flag is used in the
:doc:`compute pressure <compute_pressure>` command (turning
off temperature contributions).
----------
@ -62,40 +131,48 @@ Restart, fix_modify, output, run start/stop, minimize info
No information about this fix is written to :doc:`binary restart files <restart>`.
This fix is not imposed during minimization.
The :doc:`fix_modify <fix_modify>` *virial* option is supported by this
fix to add the contribution due to the added forces on atoms to the
system's virial as part of :doc:`thermodynamic output <thermo_style>`.
The default is *virial yes* for keywords *dipole* and *quat*. The
default is *virial no* for keyword *velocity*.
No parameter of this fix can be used with the *start/stop* keywords of
the :doc:`run <run>` command.
Restrictions
""""""""""""
In quat mode, this fix makes use of per-atom quaternions to take
into account the fact that the orientation can rotate and hence the
direction of the active force can change. The quat mode
of this fix only works with atom_style ellipsoid.
With keyword *dipole*, this fix only works when the DIPOLE package is enabled.
See the :doc:`Build package <Build_package>` doc page for more info.
This fix is part of the USER-BROWNIAN package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package <Build_package>`
doc page for more info.
Related commands
""""""""""""""""
:doc:`fix setforce <fix_setforce>`, :doc:`fix addforce <fix_addforce>`
.. _Erdmann:
**(Erdmann)** U. Erdmann , W. Ebeling, L. Schimansky-Geier, and F. Schweitzer,
Eur. Phys. J. B 15, 105-113, 2000.
.. _Henkes:
**(Henkes)** Henkes, S, Fily, Y., and Marchetti, M. C. Phys. Rev. E, 84, 040301(R), 2011.
.. _Bialke:
**(Bialke)** J. Bialke, T. Speck, and H Loewen, Phys. Rev. Lett. 108, 168301, 2012.
.. _Fily:
**(Fily)** Y. Fily and M.C. Marchetti, Phys. Rev. Lett. 108, 235702, 2012.
:doc:`fix efield <fix_efield>` , :doc:`fix setforce <fix_setforce>`,
:doc:`fix addforce <fix_addforce>`
Default
"""""""
types
none
----------
.. _Erdmann1:
**(Erdmann)** U. Erdmann , W. Ebeling, L. Schimansky-Geier, and F. Schweitzer,
Eur. Phys. J. B 15, 105-113, 2000.
.. _Winkler1:
**(Winkler)** Winkler, Wysocki, and Gompper, Soft Matter, 11, 6680 (2015).

2
doc/src/fix_tgnh_drude.rst
View File

@ -62,6 +62,8 @@ Examples
fix 2 jello tgnpt/drude temp 300.0 300.0 100.0 1.0 20.0 tri 5.0 5.0 1000.0
fix 2 ice tgnpt/drude temp 250.0 250.0 100.0 1.0 20.0 x 1.0 1.0 0.5 y 2.0 2.0 0.5 z 3.0 3.0 0.5 yz 0.1 0.1 0.5 xz 0.2 0.2 0.5 xy 0.3 0.3 0.5 nreset 1000
Example input scripts available: examples/USER/drude
Description
"""""""""""

2
doc/src/fix_wall_gran_region.rst
View File

@ -65,7 +65,7 @@ non-granular particles and simpler wall geometries, respectively.
Here are snapshots of example models using this command. Corresponding
input scripts can be found in examples/granregion. Movies of these
simulations are `here on the Movies page <https://lammps.sandia.gov/movies.html#granregion>`_
simulations are `here on the Movies page <https://www.lammps.org/movies.html#granregion>`_
of the LAMMPS web site.
.. |wallgran1| image:: img/gran_funnel.png

8
doc/src/kspace_style.rst
View File

@ -278,7 +278,7 @@ pressure simulation with MSM will cause the code to run slower.
----------
The *scafacos* style is a wrapper on the `ScaFaCoS Coulomb solver library <http://www.scafacos.de>`_ which provides a variety of solver
methods which can be used with LAMMPS. The paper by :ref:`(Who) <Who2012>`
methods which can be used with LAMMPS. The paper by :ref:`(Sutman) <Sutmann2014>`
gives an overview of ScaFaCoS.
ScaFaCoS was developed by a consortium of German research facilities
@ -550,7 +550,7 @@ Illinois at Urbana-Champaign, (2006).
**(Cerda)** Cerda, Ballenegger, Lenz, Holm, J Chem Phys 129, 234104 (2008)
.. _Who2012:
.. _Sutmann2014:
**(Who)** Who, Author2, Author3, J of Long Range Solvers, 35, 164-177
(2012).
**(Sutmann)** G. Sutmann. ScaFaCoS - a Scalable library of Fast Coulomb Solvers for particle Systems.
In Bajaj, Zavattieri, Koslowski, Siegmund, Proceedings of the Society of Engineering Science 51st Annual Technical Meeting. 2014.

88
doc/src/mdi_engine.rst Normal file
View File

@ -0,0 +1,88 @@
.. index:: mdi/engine
mdi_engine command
==================
Syntax
""""""
.. parsed-literal::
mdi_engine
Description
"""""""""""
This command is used to have LAMMPS act as a server with another
client code to effectively couple the two codes together in
client/server mode.
More specifically, this command causes LAMMPS to begin using the `MDI
Library <https://molssi-mdi.github.io/MDI_Library/html/index.html>`_
to run as an MDI engine (server), responding to commands made by an
external MDI driver code (client). See the :doc:`Howto mdi
<Howto_mdi>` doc page for more information about how LAMMPS can work
as both an MDI driver or engine.
General information about launching codes that communicate using the
MDI Library can be found in the `corresponding page
<https://molssi-mdi.github.io/MDI_Library/html/library_page.html#library_launching_sec>`_
of the MDI Library's documentation.
----------
This command should typically be used in an input script after LAMMPS
has setup the system it is going to model in collaboration with the
driver code. Depending on how the driver code tells the LAMMPS engine
to exit, other commands can be executed after this command, but
typically it should be used at the end of the LAMMPS input script.
To act as a MD-based MDI engine, this is the list of MDI commands from
a driver code which LAMMPS currently recognizes. See more details
about these commands in the `MDI library documentation
<https://molssi-mdi.github.io/MDI_Library/html/mdi_standard.html>`_
.. NOTE: Taylor - is this the best link for this info? Can we flesh this
.. out with the full list of supported commands? Maybe the distinction
.. of what "node" the commands refer to is not needed in this table?
.. list-table::
:widths: 20 80
:header-rows: 1
* - Command name
- Action
* - >NATOMS
- Driver sends the number of atoms in the system
* - <NATOMS
- Driver requests the number of atoms in the system
* - <COORDS
- Driver requests 3*N double-precision atom coordinates
* - >FORCES
- Driver sends 3*N double-precision atom forces
* - <COORDS
- Driver requests 3*N double-precision atom forces
* - EXIT
- Driver tells the engine (LAMMPS) to exit engine mode
If these commands are not sufficient to support what a driver which
you write needs, additional commands can be defined by simply using a
new command name not in this list. Code to support the new command
needs to be added to the USER-MDI package within LAMMPS; see its
src/USER-MDI/mdi_engine.cpp and fix_mdi_engine.cpp files.
Restrictions
""""""""""""
This command is part of the USER-MDI package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` doc page for more info.
Related commands
""""""""""""""""
:doc:`fix mdi/engine <fix_mdi_engine>`
Default
"""""""
None

40
doc/src/neigh_modify.rst
View File

@ -14,7 +14,7 @@ Syntax
.. parsed-literal::
keyword = *delay* or *every* or *check* or *once* or *cluster* or *include* or *exclude* or *page* or *one* or *binsize*
keyword = *delay* or *every* or *check* or *once* or *cluster* or *include* or *exclude* or *page* or *one* or *binsize* or *collection/type* or *collection/interval*
*delay* value = N
N = delay building until this many steps since last build
*every* value = M
@ -47,6 +47,12 @@ Syntax
N = max number of neighbors of one atom
*binsize* value = size
size = bin size for neighbor list construction (distance units)
*collection/type* values = N arg1 ... argN
N = number of custom collections
arg = N separate lists of types (see below)
*collection/interval* values = N arg1 ... argN
N = number of custom collections
arg = N separate cutoffs for intervals (see below)
Examples
""""""""
@ -58,6 +64,8 @@ Examples
neigh_modify exclude group frozen frozen check no
neigh_modify exclude group residue1 chain3
neigh_modify exclude molecule/intra rigid
neigh_modify collection/type 2 1*2,5 3*4
neigh_modify collection/interval 2 1.0 10.0
Description
"""""""""""
@ -188,8 +196,9 @@ atom can have.
The *binsize* option allows you to specify what size of bins will be
used in neighbor list construction to sort and find neighboring atoms.
By default, for :doc:`neighbor style bin <neighbor>`, LAMMPS uses bins
that are 1/2 the size of the maximum pair cutoff. For :doc:`neighbor style multi <neighbor>`, the bins are 1/2 the size of the minimum pair
cutoff. Typically these are good values for minimizing the time for
that are 1/2 the size of the maximum pair cutoff. For :doc:`neighbor style multi <neighbor>`,
the bins are 1/2 the size of the collection interaction cutoff.
Typically these are good values for minimizing the time for
neighbor list construction. This setting overrides the default.
If you make it too big, there is little overhead due to
looping over bins, but more atoms are checked. If you make it too
@ -197,6 +206,31 @@ small, the optimal number of atoms is checked, but bin overhead goes
up. If you set the binsize to 0.0, LAMMPS will use the default
binsize of 1/2 the cutoff.
The *collection/type* option allows you to define collections of atom
types, used by the *multi* neighbor mode. By grouping atom types with
similar physical size or interaction cutoff lengths, one may be able
to improve performance by reducing
overhead. You must first specify the number of collections N to be
defined followed by N lists of types. Each list consists of a series of type
ranges separated by commas. The range can be specified as a
single numeric value, or a wildcard asterisk can be used to specify a range
of values. This takes the form "\*" or "\*n" or "n\*" or "m\*n". For
example, if M = the number of atom types, then an asterisk with no numeric
values means all types from 1 to M. A leading asterisk means all types
from 1 to n (inclusive). A trailing asterisk means all types from n to M
(inclusive). A middle asterisk means all types from m to n (inclusive).
Note that all atom types must be included in exactly one of the N collections.
The *collection/interval* option provides a similar capability. This
command allows a user to define collections by specifying a series of
cutoff intervals. LAMMPS will automatically sort atoms into these
intervals based on their type-dependent cutoffs or their finite size.
You must first specify the number of collections N to be defined
followed by N values representing the upper cutoff of each interval.
This command is particularly useful for granular pair styles where the
interaction distance of particles depends on their radius and may not
depend on their atom type.
Restrictions
""""""""""""

39
doc/src/neighbor.rst
View File

@ -11,7 +11,7 @@ Syntax
neighbor skin style
* skin = extra distance beyond force cutoff (distance units)
* style = *bin* or *nsq* or *multi*
* style = *bin* or *nsq* or *multi* or *multi/old*
Examples
""""""""
@ -55,14 +55,31 @@ For the *bin* style, the bin size is set to 1/2 of
the largest cutoff distance between any pair of atom types and a
single set of bins is defined to search over for all atom types. This
can be inefficient if one pair of types has a very long cutoff, but
other type pairs have a much shorter cutoff. For style *multi* the
bin size is set to 1/2 of the shortest cutoff distance and multiple
sets of bins are defined to search over for different atom types.
other type pairs have a much shorter cutoff. The *multi* style uses
different sized bins for collections of different sized particles, where
"size" may mean the physical size of the particle or its cutoff
distance for interacting with other particles. Different
sets of bins are then used to construct the neighbor lists as as further
described by Shire, Hanley, and Stratford :ref:`(Shire) <bytype-Shire>`.
This imposes some extra setup overhead, but the searches themselves
may be much faster for the short-cutoff cases.
See the :doc:`comm_modify mode multi <comm_modify>` command for a
communication option that may also be beneficial for simulations of
this kind.
may be much faster. By default, each atom type defines a separate
collection of particles. For systems where two or more atom types
have the same size (either physical size or cutoff distance), the
definition of collections can be customized, which can result in less
overhead and faster performance. See the :doc:`neigh_modify <neigh_modify>`
command for how to define custom collections. Whether the collection
definition is customized or not, also see the
:doc:`comm_modify mode multi <comm_modify>` command for communication
options that further improve performance in a manner consistent with
neighbor style multi.
An alternate style, *multi/old*, sets the bin size to 1/2 of the shortest
cutoff distance and multiple sets of bins are defined to search over for
different atom types. This algorithm used to be the default *multi*
algorithm in LAMMPS but was found to be significantly slower than the new
approach. For now we are keeping the old option in case there are use cases
where multi/old outperforms the new multi style.
The :doc:`neigh_modify <neigh_modify>` command has additional options
that control how often neighbor lists are built and which pairs are
@ -90,3 +107,9 @@ Default
| 0.001 bin for units = si, skin = 0.001 meters = 1.0 mm
| 0.1 bin for units = cgs, skin = 0.1 cm = 1.0 mm
|
----------
.. _bytype-Shire:
**(Shire)** Shire, Hanley and Stratford, Comp Part Mech, (2020).

1
doc/src/pair_coul_tt.rst
View File

@ -29,6 +29,7 @@ Examples
pair_coeff 1 2 coul/tt 4.0 1.0 4 12.0
pair_coeff 1 3* coul/tt 4.5 1.0 4
Example input scripts available: examples/USER/drude
Description
"""""""""""

138
doc/src/pair_dpd_ext.rst Normal file
View File

@ -0,0 +1,138 @@
.. index:: pair_style dpd/ext
.. index:: pair_style dpd/ext/tstat
pair_style dpd/ext command
==========================
pair_style dpd/ext/tstat command
================================
Syntax
""""""
.. code-block:: LAMMPS
pair_style dpd/ext T cutoff seed
pair_style dpd/ext/tstat Tstart Tstop cutoff seed
* T = temperature (temperature units)
* Tstart,Tstop = desired temperature at start/end of run (temperature units)
* cutoff = global cutoff for DPD interactions (distance units)
* seed = random # seed (positive integer)
Examples
""""""""
.. code-block:: LAMMPS
pair_style dpd/ext 1.0 2.5 34387
pair_coeff 1 1 25.0 4.5 4.5 0.5 0.5 1.2
pair_coeff 1 2 40.0 4.5 4.5 0.5 0.5 1.2
pair_style dpd/ext/tstat 1.0 1.0 2.5 34387
pair_coeff 1 1 4.5 4.5 0.5 0.5 1.2
pair_coeff 1 2 4.5 4.5 0.5 0.5 1.2
Description
"""""""""""
The style *dpd/ext* computes an extended force field for dissipative particle dynamics (DPD) following the exposition in :ref:`(Groot) <Groot>`, :ref:`(Junghans) <Junghans>`.
Style *dpd/ext/tstat* invokes an extended DPD thermostat on pairwise interactions, equivalent to the non-conservative portion of the extended DPD force field. To use *dpd/ext/tstat* as a thermostat for another pair style, use the :doc:`pair_style hybrid/overlay <pair_hybrid>` command to compute both the desired pair interaction and the thermostat for each pair of particles.
For the style *dpd/ext*\ , the force on atom I due to atom J is given as a sum
of 3 terms
.. math::
\mathbf{f} = & f^C + f^D + f^R \qquad \qquad r < r_c \\
f^C = & A_{ij} w(r) \hat{\mathbf{r}}_{ij} \\
f^D = & - \gamma_{\parallel} w_{\parallel}^2(r) (\hat{\mathbf{r}}_{ij} \cdot \mathbf{v}_{ij}) \hat{\mathbf{r}}_{ij} - \gamma_{\perp} w_{\perp}^2 (r) ( \mathbf{I} - \hat{\mathbf{r}}_{ij} \hat{\mathbf{r}}_{ij}^{\rm T} ) \mathbf{v}_{ij} \\
f^R = & \sigma_{\parallel} w_{\parallel}(r) \frac{\alpha}{\sqrt{\Delta t}} \hat{\mathbf{r}}_{ij} + \sigma_{\perp} w_{\perp} (r) ( \mathbf{I} - \hat{\mathbf{r}}_{ij} \hat{\mathbf{r}}_{ij}^{\rm T} ) \frac{\mathbf{\xi}_{ij}}{\sqrt{\Delta t}}\\
w(r) = & 1 - r/r_c \\
where :math:`\mathbf{f}^C` is a conservative force, :math:`\mathbf{f}^D` is a dissipative force, and :math:`\mathbf{f}^R` is a random force. :math:`A_{ij}` is the maximum repulsion between the two atoms, :math:`\hat{\mathbf{r}}_{ij}` is a unit vector in the direction :math:`\mathbf{r}_i - \mathbf{r}_j`, :math:`\mathbf{v}_{ij} = \mathbf{v}_i - \mathbf{v}_j` is the vector difference in velocities of the two atoms, :math:`\alpha` and :math:`\mathbf{\xi}_{ij}` are Gaussian random numbers with zero mean and unit variance, :math:`\Delta t` is the timestep, :math:`w (r) = 1 - r / r_c` is a weight function for the conservative interactions that varies between 0 and 1, :math:`r_c` is the corresponding cutoff, :math:`w_{\alpha} ( r ) = ( 1 - r / \bar{r}_c )^{s_{\alpha}}`, :math:`\alpha \equiv ( \parallel, \perp )`, are weight functions with coefficients :math:`s_\alpha` that vary between 0 and 1, :math:`\bar{r}_c` is the corresponding cutoff, :math:`\mathbf{I}` is the unit matrix, :math:`\sigma_{\alpha} = \sqrt{2 k T \gamma_{\alpha}}`, where :math:`k` is the Boltzmann constant and :math:`T` is the temperature in the pair\_style command.
For the style *dpd/ext/tstat*\ , the force on atom I due to atom J is the same as the above equation, except that the conservative :math:`\mathbf{f}^C` term is dropped. Also, during the run, T is set each timestep to a ramped value from Tstart to Tstop.
For the style *dpd/ext*\ , the pairwise energy associated with style *dpd/ext* is only due to the conservative force term :math:`\mathbf{f}^C`, and is shifted to be zero at the cutoff distance :math:`r_c`. The pairwise virial is calculated using all three terms. There is no pairwise energy for style *dpd/ext/tstat*, but the last two terms of the formula contribute the virial.
For the style *dpd/ext/tstat*, the force on atom I due to atom J is the same as the above equation, except that the conservative :math:`\mathbf{f}^C` term is dropped. Also, during the run, T is set each timestep to a ramped value from Tstart to Tstop.
For the style *dpd/ext*\ , the pairwise energy associated with style *dpd/ext* is only due to the conservative force term :math:`\mathbf{f}^C`, and is shifted to be zero at the cutoff distance :math:`r_c`. The pairwise virial is calculated using all three terms. There is no pairwise energy for style *dpd/ext/tstat*, but the last two terms of the formula contribute the virial.
For the style *dpd/ext*, the following coefficients must be defined for each pair of atoms types via the :doc:`pair_coeff <pair_coeff>` command as in the examples above:
* A (force units)
* :math:`\gamma_{\perp}` (force/velocity units)
* :math:`\gamma_{\parallel}` (force/velocity units)
* :math:`s_{\perp}` (unitless)
* :math:`s_{\parallel}` (unitless)
* :math:`r_c` (distance units)
The last coefficient is optional. If not specified, the global DPD cutoff is used. Note that :math:`\sigma`'s are set equal to :math:`\sqrt{2 k T \gamma}`, where :math:`T` is the temperature set by the :doc:`pair_style <pair_style>` command so it does not need to be specified.
For the style *dpd/ext/tstat*, the coefficients defined for each pair of atoms types via the :doc:`pair_coeff <pair_coeff>` command is the same, except that A is not included.
.. note::
If you are modeling DPD polymer chains, you may want to use the :doc:`pair_style srp <pair_srp>` command in conjunction with these pair styles. It is a soft segmental repulsive potential (SRP) that can prevent DPD polymer chains from crossing each other.
.. note::
The virial calculation for pressure when using this pair style includes all the components of force listed above, including the random force.
----------
**Mixing, shift, table, tail correction, restart, rRESPA info**\ :
The style *dpd/ext* does not support mixing. Thus, coefficients for all I,J pairs must be specified explicitly.
The pair styles do not support the :doc:`pair_modify <pair_modify>` shift option for the energy of the pair interaction. Note that as discussed above, the energy due to the conservative :math:`\mathbf{f}^C` term is already shifted to be zero at the cutoff distance :math:`r_c`.
The :doc:`pair_modify <pair_modify>` table option is not relevant for the style *dpd/ext*.
The style *dpd/ext* does not support the :doc:`pair_modify <pair_modify>` tail option for adding long-range tail corrections to energy and pressure.
The pair styles can only be used via the pair keyword of the :doc:`run_style respa <run_style>` command. They do not support the *inner*\ , *middle*\ , and *outer*\ keywords.
The style *dpd/ext/tstat* can ramp its target temperature over multiple runs, using the start and stop keywords of the :doc:`run <run>` command. See the :doc:`run <run>` command for details of how to do this.
----------
Restrictions
""""""""""""
The default frequency for rebuilding neighbor lists is every 10 steps (see the :doc:`neigh_modify <neigh_modify>` command). This may be too infrequent for style *dpd/ext* simulations since particles move rapidly and can overlap by large amounts. If this setting yields a non-zero number of \say{dangerous} reneighborings (printed at the end of a simulation), you should experiment with forcing reneighboring more often and see if system energies/trajectories change.
The pair styles require to use the :doc:`comm_modify vel yes <comm_modify>` command so that velocities are stored by ghost atoms.
The pair styles will not restart exactly when using the :doc:`read_restart <read_restart>` command, though they should provide statistically similar results. This is because the forces they compute depend on atom velocities. See the :doc:`read_restart <read_restart>` command for more details.
Related commands
""""""""""""""""
:doc:`pair_style dpd <pair_dpd>`, :doc:`pair_coeff <pair_coeff>`, :doc:`fix nvt <fix_nh>`, :doc:`fix langevin <fix_langevin>`, :doc:`pair_style srp <pair_srp>`
**Default:** none
----------
.. _Groot:
**(Groot)** Groot and Warren, J Chem Phys, 107, 4423-35 (1997).
.. _Junghans:
**(Junghans)** Junghans, Praprotnik and Kremer, Soft Matter 4, 156, 1119-1128 (2008).

2
doc/src/pair_fep_soft.rst
View File

@ -182,6 +182,8 @@ Examples
pair_coeff * * 100.0 2.0 1.5 1.0
pair_coeff 1 1 100.0 2.0 1.5 1.0 3.0
Example input scripts available: examples/USER/fep
Description
"""""""""""

230
doc/src/pair_hdnnp.rst Normal file
View File

@ -0,0 +1,230 @@
.. index:: pair_style hdnnp
pair_style hdnnp command
========================
Syntax
""""""
.. code-block:: LAMMPS
pair_style hdnnp cutoff keyword value ...
* cutoff = short-range cutoff of HDNNP (maximum symmetry function cutoff radius)
* zero or more keyword/value pairs may be appended
* keyword = *dir* or *showew* or *showewsum* or *maxew* or *resetew* or *cflength* or *cfenergy*
* value depends on the preceding keyword:
.. parsed-literal::
*dir* value = directory
directory = Path to HDNNP configuration files
*showew* value = *yes* or *no*
*showewsum* value = summary
summary = Write EW summary every this many timesteps (*0* turns summary off)
*maxew* value = threshold
threshold = Maximum number of EWs allowed
*resetew* value = *yes* or *no*
*cflength* value = length
length = Length unit conversion factor
*cfenergy* value = energy
energy = Energy unit conversion factor
Examples
""""""""
.. code-block:: LAMMPS
pair_style hdnnp 6.35 showew yes showewsum 100 maxew 1000 resetew yes cflength 1.8897261328 cfenergy 0.0367493254
pair_coeff * * H O
pair_style hdnnp 6.01 dir "./" showewsum 10000
pair_coeff * * S Cu NULL Cu
Description
"""""""""""
This pair style adds an interaction based on the high-dimensional neural network
potential (HDNNP) method as presented in :ref:`(Behler and Parrinello 2007)
<Behler_Parrinello_2007>`. HDNNPs are machine learning potentials which require
careful training of neural networks prior to application in MD simulations. The
pair style uses an interface to the *n2p2* library :ref:`(Singraber, Behler and
Dellago 2019) <Singraber_Behler_Dellago_2019>` which is available on Github
`here <https://github.com/CompPhysVienna/n2p2>`__. Please see the *n2p2*
`documentation <https://compphysvienna.github.io/n2p2/>`__ for further details.
*n2p2* (and hence this pair style) is compatible with neural network potentials
trained with its own tools :ref:`(Singraber et al 2019) <Singraber_et_al_2019>`
and with `RuNNer <https://www.uni-goettingen.de/de/560580.html>`__.
Only a single *pair_coeff* command with two asterisk wild-cards is used with this
pair style. Its additional arguments define the mapping of LAMMPS atom types to
n2p2 elements.
.. code-block:: LAMMPS
pair_coeff * * H O
In the above example LAMMPS types 1 and 2 are mapped to the elements "H" and "O"
in n2p2, respectively. Multiple types may map to the same element, or some types
may not be mapped at all. For example, if the LAMMPS simulation has four atom
types, the command
.. code-block:: LAMMPS
pair_coeff * * H H O NULL
maps atom types 1 and 2 to the element "H", type 3 to "O" and type 4 is not mapped
(indicated by NULL). Atoms mapped to NULL are ignored by the HDNNP calculation,
i.e. they do not contribute in any way to the evaluation of HDNNP energies and forces.
This may be useful in a setup with :doc:`hybrid pair styles <pair_hybrid>`.
----
The mandatory pair style argument *cutoff* must match the short-range cutoff radius
of the HDNNP. This corresponds to the maximum cutoff radius of all symmetry
functions (the atomic environment descriptors of HDNNPs) used.
.. note::
The cutoff must be given in LAMMPS length units, even if the neural network
potential has been trained using a different unit system (see remarks about the
*cflength* and *cfenergy* keywords below for details).
The numeric value may be slightly larger than the actual maximum symmetry
function cutoff radius (to account for rounding errors when converting units),
but must not be smaller.
Use the *dir* keyword to specify the directory containing the HDNNP configuration
files. The directory must contain ``input.nn`` with neural network and symmetry
function setup, ``scaling.data`` with symmetry function scaling data and
``weights.???.data`` with weight parameters for each element.
The keyword *showew* can be used to turn on/off the display of extrapolation
warnings (EWs) which are issued whenever a symmetry function value is out of
bounds defined by minimum/maximum values in ``scaling.data``. An extrapolation
warning may look like this:
.. code-block:: LAMMPS
### NNP EXTRAPOLATION WARNING ### STRUCTURE: 0 ATOM: 119 ELEMENT: Cu SYMFUNC: 32 TYPE: 3 VALUE: 2.166E-02 MIN: 2.003E-05 MAX: 1.756E-02
stating that the value 2.166E-02 of symmetry function 32 of type 3 (Narrow Angular symmetry function), element Cu (see the log file for a symmetry function listing) was out
of bounds (maximum in ``scaling.data`` is 1.756E-02) for atom 119. Here, the
atom index refers to the LAMMPS tag (global index) and the structure index is
used to print out the MPI rank the atom belongs to.
.. note::
The *showew* keyword should only be set to *yes* for debugging purposes.
Extrapolation warnings may add lots of overhead as they are communicated each
timestep. Also, if the simulation is run in a region where the HDNNP was not
correctly trained, lots of extrapolation warnings may clog log files and the
console. In a production run use *showewsum* instead.
The keyword *showewsum* can be used to get an overview of extrapolation warnings
occurring during an MD simulation. The argument specifies the interval at which
extrapolation warning summaries are displayed and logged. An EW summary may look
like this:
.. code-block:: LAMMPS
### NNP EW SUMMARY ### TS: 100 EW 11 EWPERSTEP 1.100E-01
Here, at timestep 100 the occurrence of 11 extrapolation warnings since the last
summary is reported, which corresponds to an EW rate of 0.11 per timestep.
Setting *showewsum* to 0 deactivates the EW summaries.
A maximum number of allowed extrapolation warnings can be specified with the
*maxew* keyword. If the number of EWs exceeds the *maxew* argument the
simulation is stopped. Note however that this is merely an approximate threshold
since the check is only performed at the end of each timestep and each MPI
process counts individually to minimize communication overhead.
The keyword *resetew* alters the behavior of the above mentioned *maxew*
threshold. If *resetew* is set to *yes* the threshold is applied on a
per-timestep basis and the internal EW counters are reset at the beginning of
each timestep. With *resetew* set to *no* the counters accumulate EWs along the
whole trajectory.
If the training of a neural network potential has been performed with different
physical units for length and energy than those set in LAMMPS, it is still
possible to use the potential when the unit conversion factors are provided via
the *cflength* and *cfenergy* keywords. If for example, the HDNNP was
parameterized with Bohr and Hartree training data and symmetry function
parameters (i.e. distances and energies in "input.nn" are given in Bohr and
Hartree) but LAMMPS is set to use *metal* units (Angstrom and eV) the correct
conversion factors are:
.. code-block:: LAMMPS
cflength 1.8897261328
cfenergy 0.0367493254
Thus, arguments of *cflength* and *cfenergy* are the multiplicative factors
required to convert lengths and energies given in LAMMPS units to respective
quantities in native HDNNP units (1 Angstrom = 1.8897261328 Bohr, 1 eV =
0.0367493254 Hartree).
----
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
This style does not support mixing. The :doc:`pair_coeff <pair_coeff>` command
should only be invoked with asterisk wild cards (see above).
This style does not support the :doc:`pair_modify <pair_modify>`
shift, table, and tail options.
This style does not write information to :doc:`binary restart files <restart>`.
Thus, you need to re-specify the pair_style and pair_coeff commands in an input
script that reads a restart file.
This style can only be used via the *pair* keyword of the :doc:`run_style respa
<run_style>` command. It does not support the *inner*\ , *middle*\ , *outer*
keywords.
Restrictions
""""""""""""
This pair style is part of the USER-HDNNP package. It is only enabled if LAMMPS
was built with that package. See the :doc:`Build package <Build_package>` doc
page for more info.
Please report bugs and feature requests to the `n2p2 GitHub issue page
<https://github.com/CompPhysVienna/n2p2/issues>`__.
Related commands
^^^^^^^^^^^^^^^^
:doc:`pair_coeff <pair_coeff>`, :doc:`pair_hybrid <pair_hybrid>`, :doc:`units <units>`
Default
^^^^^^^
The default options are *dir* = "hdnnp/", *showew* = yes, *showewsum* = 0, *maxew*
= 0, *resetew* = no, *cflength* = 1.0, *cfenergy* = 1.0.
----
.. _Behler_Parrinello_2007:
**(Behler and Parrinello 2007)** `Behler, J.; Parrinello, M. Generalized
Neural-Network Representation of High-Dimensional Potential-Energy Surfaces.
Phys. Rev. Lett. 2007, 98 (14), 146401.
<https://doi.org/10.1103/PhysRevLett.98.146401>`__
.. _Singraber_Behler_Dellago_2019:
**(Singraber, Behler and Dellago 2019)** `Singraber, A.; Behler, J.; Dellago, C.
Library-Based LAMMPS Implementation of High-Dimensional Neural Network
Potentials. J. Chem. Theory Comput. 2019, 15 (3), 1827-1840
<https://doi.org/10.1021/acs.jctc.8b00770>`__
.. _Singraber_et_al_2019:
**(Singraber et al 2019)** `Singraber, A.; Morawietz, T.; Behler, J.; Dellago,
C. Parallel Multistream Training of High-Dimensional Neural Network Potentials.
J. Chem. Theory Comput. 2019, 15 (5), 3075-3092.
<https://doi.org/10.1021/acs.jctc.8b01092>`__

12
doc/src/pair_hybrid.rst
View File

@ -257,7 +257,7 @@ then overrides them with 0.0 only for CHARMM:
.. code-block:: LAMMPS
special_bonds amber
pair_hybrid lj/charmm/coul/long 8.0 10.0 lj/cut/coul/long 10.0
pair_style hybrid lj/charmm/coul/long 8.0 10.0 lj/cut/coul/long 10.0
pair_modify pair lj/charmm/coul/long special lj/coul 0.0 0.0 0.0
The this input achieves the same effect:
@ -265,7 +265,7 @@ The this input achieves the same effect:
.. code-block:: LAMMPS
special_bonds 0.0 0.0 0.1
pair_hybrid lj/charmm/coul/long 8.0 10.0 lj/cut/coul/long 10.0
pair_style hybrid lj/charmm/coul/long 8.0 10.0 lj/cut/coul/long 10.0
pair_modify pair lj/cut/coul/long special lj 0.0 0.0 0.5
pair_modify pair lj/cut/coul/long special coul 0.0 0.0 0.83333333
pair_modify pair lj/charmm/coul/long special lj/coul 0.0 0.0 0.0
@ -279,7 +279,7 @@ effectively *lj/coul 0.0 0.0 0.5* as required for OPLS/AA:
.. code-block:: LAMMPS
special_bonds lj/coul 1e-20 1e-20 0.5
pair_hybrid tersoff lj/cut/coul/long 12.0
pair_style hybrid tersoff lj/cut/coul/long 12.0
pair_modify pair tersoff special lj/coul 1.0 1.0 1.0
For use with the various :doc:`compute \*/tally <compute_tally>`
@ -417,7 +417,11 @@ assigned automatically to the sub-style defined for both I,I and J,J and
its coefficients generated by the mixing rule used by that sub-style.
For the *hybrid/overlay* and *hybrid/scaled* style, there is an
additional requirement that both the I,I and J,J pairs are assigned to a
single sub-style. See the :doc:`pair_modify <pair_modify>` command for
single sub-style. If this requirement is not met, no I,J coeffs will be
generated, even if the sub-styles support mixing, and I,J pair
coefficients must be explicitly defined.
See the :doc:`pair_modify <pair_modify>` command for
details of mixing rules. See the See the doc page for the sub-style to
see if allows for mixing.

16
doc/src/pair_lj_cut_tip4p.rst
View File

@ -145,6 +145,22 @@ specified since a Coulombic cutoff cannot be specified for an individual I,J
type pair. All type pairs use the same global Coulombic cutoff specified in
the pair_style command.
.. warning::
Because of how these pair styles implement the coulomb interactions
by implicitly defining a fourth site for the negative charge
of the TIP4P and similar water models, special care must be taken
when using these pair styles with other computations that also use
charges. Unless they are specially set up to also handle the implicit
definition of the 4th site, results are likely incorrect. Example:
:doc:`compute dipole/chunk <compute_dipole_chunk>`. For the same
reason, when using one of these pair styles with
:doc:`pair_style hybrid <pair_hybrid>`, **all** coulomb interactions
should be handled by a single sub-style with TIP4P support. All other
instances and styles will "see" the M point charges at the position
of the Oxygen atom and thus compute incorrect forces and energies.
LAMMPS will print a warning when it detects one of these issues.
----------
A version of these styles with a soft core, *lj/cut/tip4p/long/soft*\ , suitable

3
doc/src/pair_lj_smooth.rst
View File

@ -1,10 +1,11 @@
.. index:: pair_style lj/smooth
.. index:: pair_style lj/smooth/gpu
.. index:: pair_style lj/smooth/omp
pair_style lj/smooth command
============================
Accelerator Variants: *lj/smooth/omp*
Accelerator Variants: *lj/smooth/gpu*, *lj/smooth/omp*
Syntax
""""""

412
doc/src/pair_rann.rst Normal file
View File

@ -0,0 +1,412 @@
.. index:: pair_style rann
pair_style rann command
=======================
Syntax
""""""
.. code-block:: LAMMPS
pair_style rann
pair_coeff file Type1_element Type2_element Type3_element...
Examples
""""""""
.. code-block:: LAMMPS
pair_style rann
pair_coeff ** Mg.rann Mg
pair_coeff ** MgAlalloy.rann Mg Mg Al Mg
Description
"""""""""""
Pair style *rann* computes pairwise interactions for a variety of
materials using rapid atomistic neural network (RANN) potentials
(:ref:`Dickel <Dickel>` , :ref:`Nitol <Nitol>`). Neural network
potentials work by first generating a series of symmetry functions
i.e. structural fingerprints from the neighbor list and then using these
values as the input layer of a neural network. There is a single output
neuron in the final layer which is the energy. Atomic forces are found
by analytical derivatives computed via back-propagation. For alloy
systems, each element has a unique network.
Potential file syntax
"""""""""""""""""""""
The RANN potential is defined by a single text file which contains all
the fitting parameters for the alloy system. The potential file also
defines the active fingerprints, network architecture, activation
functions, etc. The potential file is divided into several sections
which are identified by one of the following keywords:
* atomtypes
* mass
* fingerprintsperelement
* fingerprints
* fingerprintconstants
* screening (optional)
* networklayers
* layersize
* weight
* bias
* activationfunctions
* calibrationparameters (ignored)
The '#' character is treated as a comment marker, similar to LAMMPS
input scripts. Sections are not required to follow a rigid ordering,
but do require previous definition of prerequisite information. E.g.,
fingerprintconstants for a particular fingerprint must follow the
fingerprints definition; layersize for a particular layer must follow
the declaration of network layers.
*atomtypes* are defined as follows using element keywords separated by spaces.
.. code-block::
atomtypes:
Fe Mg Al etc.
*mass* must be specified for each element keyword as follows:
.. code-block::
mass:Mg:
24.305
mass:Fe:
55.847
mass:Al:
26.982
*fingerprintsperelement* specifies how many fingerprints are active for
computing the energy of a given atom. This number must be specified for
each element keyword. Active elements for each fingerprint depend upon
the type of the central atom and the neighboring atoms. Pairwise
fingerprints may be defined for a Mg atom based exclusively on its Al
neighbors, for example. Bond fingerprints may use two neighbor lists of
different element types. In computing fingerprintsperelement from all
defined fingerprints, only the fingerprints defined for atoms of a
particular element should be considered, regardless of the elements used
in its neighbor list. In the following code, for example, some
fingerprints may compute pairwise fingerprints summing contributions
about Fe atoms based on a neighbor list of exclusively Al atoms, but if
there are no fingerprints summing contributions of all neighbors about a
central Al atom, then fingerprintsperelement of Al is zero:
.. code-block::
fingerprintsperelement:Mg:
5
fingerprintsperelement:Fe:
2
fingerprintsperelement:Al:
0
*fingerprints* specifies the active fingerprints for a certain element
combination. Pair fingerprints are specified for two elements, while
bond fingerprints are specified for three elements. Only one
fingerprints header should be used for an individual combination of
elements. The ordering of the fingerprints in the network input layer
is determined by the order of element combinations specified by
subsequent *fingerprints* lines, and the order of the fingerprints
defined for each element combination. Multiple fingerprints of the same
style or different ones may be specified. If the same style and element
combination is used for multiple fingerprints, they should have
different id numbers. The first element specifies the atoms for which
this fingerprint is computed while the other(s) specify which atoms to
use in the neighbor lists for the computation. Switching the second and
third element type in bond fingerprints has no effect on the
computation:
.. code-block::
fingerprints:Mg_Mg:
radial_0 radialscreened_0 radial_1
fingerprints:Mg_Al_Fe:
bond_0 bondspin_0
fingerprints:Mg_Al:
radial_0 radialscreened_0
The following fingerprint styles are currently defined. See the
:ref:`formulation section <fingerprints>` below for their definitions:
* radial
* radialscreened
* radialspin
* radialscreenedspin
* bond
* bondscreened
* bondspin
* bondscreenedspin
*fingerprintconstants* specifies the meta-parameters for a defined fingerprint. For all radial styles, re, rc,
alpha, dr, o, and n must be specified. re should usually be the stable interatomic distance, rc is the cutoff
radius, dr is the cutoff smoothing distance, o is the lowest radial power term (which may be negative), and n
is the highest power term. The total length of the fingerprint vector is (n-o+1). alpha is a list of decay parameters
used for exponential decay of radial contributions. It may be set proportionally to the bulk modulus similarly
to MEAM potentials, but other values may provided better fitting in special cases. Bond style fingerprints require
specification of re, rc, alphak, dr, k, and m. Here m is the power of the bond cosines and k is the number of
decay parameters. Cosine powers go from 0 to m-1 and are each computed for all values of alphak. Thus the total
length of the fingerprint vector is m*k.
.. code-block::
fingerprintconstants:Mg_Mg:radialscreened_0:re:
3.193592
fingerprintconstants:Mg_Mg:radialscreened_0:rc:
6.000000
fingerprintconstants:Mg_Mg:radialscreened_0:alpha:
5.520000 5.520000 5.520000 5.520000 5.520000
fingerprintconstants:Mg_Mg:radialscreened_0:dr:
2.806408
fingerprintconstants:Mg_Mg:radialscreened_0:o:
-1
fingerprintconstants:Mg_Mg:radialscreened_0:n:
3
*screening* specifies the Cmax and Cmin values used in the screening
fingerprints. Contributions form neighbors to the fingerprint are
omitted if they are blocked by a closer neighbor, and reduced if they
are partially blocked. Larger values of Cmin correspond to neighbors
being blocked more easily. Cmax cannot be greater than 3, and Cmin
cannot be greater than Cmax or less than zero. Screening may be omitted
in which case the default values Cmax = 2.8, Cmin = 0.8 are used. Since
screening is a bond computation, it is specified separately for each
combination of three elements in which the latter two may be
interchanged with no effect.
.. code-block::
screening:Mg_Mg_Mg:Cmax:
2.700000
screening:Mg_Mg_Mg:Cmin:
0.400000
*networklayers* species the size of the neural network for each atom.
It counts both the input and output layer and so is 2 + \<hidden layers\>.
.. code-block::
networklayers:Mg:
3
*layersize* specifies the length of each layer, including the input
layer and output layer. The input layer is layer 0. The size of the
input layer size must match the summed length of all the fingerprints
for that element, and the output layer size must be 1:
.. code-block::
layersize:Mg:0:
14
layersize:Mg:1:
20
layersize:Mg:2:
1
*weight* specifies the weight for a given element and layer. Weight
cannot be specified for the output layer. The weight of layer i is a
*m* x *n* matrix where *m* is the layer size of *i* and *n* is the layer size of
*i*\ +1:
.. code-block::
weight:Mg:0:
w11 w12 w13 ...
w21 w22 w23 ...
...
*bias* specifies the bias for a given element and layer. Bias cannot be
specified for the output layer. The bias of layer i is a nx1 vector
where n is the layer size of i+1:
.. code-block::
bias:Mg:0:
b1
b2
b3
...
*activationfunctions* specifies the activation function for a given
element and layer. Activation functions cannot be specified for the
output layer:
.. code-block::
activationfunctions:Mg:0:
sigI
activationfunctions:Mg:1:
linear
The following activation styles are currently specified. See the
:ref:`formulation section <activations>` below for their definitions.
* sigI
* linear
*calibrationparameters* specifies a number of parameters used to calibrate the potential. These are ignored
by LAMMPS.
Formulation
"""""""""""
In the RANN formulation, the total energy of a system of atoms
is given by:
.. math::
E = \sum_{\alpha} E^{\alpha}\\\\
E^{\alpha} = {}^{N}\!A^{\alpha}\\\\
{}^{n+1}\!A_i^{\alpha} = {}^{n}\!F\left({}^{n}\!W_{ij}{\;}^{n}\!A_j^{\alpha}+{}^{n}\!B_i\right)\\\\
{}^{0}\!A_i^{\alpha} = \left[\begin{array}{c} {}^1\!S\!f^\alpha\\ {}^2\!S\!f^\alpha \\...\\\end{array}\right]
Here :math:`E^\alpha` is the energy of atom :math:`\alpha`,
:math:`{}^n\!F()`, :math:`{}^n\!W_{ij}` and :math:`{}^n\!B_i` are the
activation function, weight matrix and bias vector of the n-th layer
respectively. The inputs to the first layer are a collection of
structural fingerprints which are collected and reshaped into a single
long vector. The individual fingerprints may be defined in any order
and have various shapes and sizes. Multiple fingerprints of the same
type and varying parameters may also be defined in the input layer.
Eight types of structural fingerprints are currently defined. In the
following, :math:`\beta` and :math:`\gamma` span the full neighbor list
of atom :math:`\alpha`. :math:`\delta_i` are decay meta-parameters, and
:math:`r_e` is a meta-parameter roughly proportional to the first
neighbor distance. :math:`r_c` and :math:`dr` are the neighbor cutoff
distance and cutoff smoothing distance respectively.
:math:`S^{\alpha\beta}` is the MEAM screening function :ref:`(Baskes)
<Baskes97>`, :math:`s_i^\alpha` and :math:`s_i^\beta` are the atom spin
vectors :ref:`(Tranchida) <Tranchida7>`. :math:`r^{\alpha\beta}` is the
distance from atom :math:`\alpha` to atom :math:`\beta`, and
:math:`\theta^{\alpha\beta\gamma}` is the bond angle:
.. math ::
cos\left(\theta^{\alpha\beta\gamma}\right)=\frac{\mathbf{r}^{\alpha\beta} \cdot \mathbf{r}^{\alpha\gamma}}{r^{\alpha\beta}r^{\alpha\gamma}}
:math:`S^{\alpha\beta}` is defined as :ref:`(Baskes) <Baskes97>`:
.. math::
X^{\gamma\beta} = \left(\frac{r^{\gamma\beta}}{r^{\alpha\beta}}\right)^2\\
\\
X^{\alpha\gamma} = \left(\frac{r^{\alpha\gamma}}{r^{\alpha\beta}}\right)^2\\
\\
C = \frac{2\left(X^{\alpha\gamma}+X^{\gamma\beta}\right)-\left(X^{\alpha\gamma}-X^{\gamma\beta}\right)^2-1}{1-\left(X^{\alpha\gamma}-X^{\gamma\beta}\right)^2}\\
\\
f_c(x) = \left[\begin{array}{l} 1 \; \: x \geq 1\\ \left(1-\left(1-x\right)^4\right)^2 \; \: 0<x<1\\0\; \; x\leq0\end{array}\right.\\
\\
S^{\alpha\beta\gamma} = f_c\left(\frac{C-C_{min}}{C_{max}-C_{min}}\right)\\
\\
S^{\alpha\beta} = \prod_\gamma S^{\alpha\beta\gamma}\\
The structural fingerprints are computed as follows:
.. _fingerprints:
* **radial**
.. math::
{}^r\!S\!f_i^\alpha = \sum_{\beta} \left(\frac{r^{\alpha\beta}}{r_e}\right)^ie^{-\delta_i \frac{r^{\alpha\beta}}{r_e}}f_c\left(\frac{r_c-r^{\alpha\beta}}{dr}\right)
* **bond**
.. math::
{}^b\!S\!f_{ij}^\alpha = \sum_{\beta}\sum_{\gamma} \left(cos(\theta_{\alpha\beta\gamma})\right)^ie^{-\delta_j \frac{r^{\alpha\beta}}{r_e}}e^{-\delta_j \frac{r^{\alpha\gamma}}{r_e}}f_c\left(\frac{r_c-r^{\alpha\beta}}{dr}\right)f_c\left(\frac{r_c-r^{\alpha\gamma}}{dr}\right)
* **radialscreened**
.. math::
{}^{rsc}\!S\!f_i^\alpha = \sum_{\beta} \left(\frac{r^{\alpha\beta}}{r_e}\right)^ie^{-\delta_i \frac{r^{\alpha\beta}}{r_e}}S^{\alpha\beta}f_c\left(\frac{r_c-r^{\alpha\beta}}{dr}\right)
* **bondscreened**
.. math::
{}^{bsc}\!S\!f_{ij}^\alpha = \sum_{\beta}\sum_{\gamma} \left(cos(\theta_{\alpha\beta\gamma})\right)^ie^{-\delta_j \frac{r^{\alpha\beta}}{r_e}}e^{-\delta_j \frac{r^{\alpha\gamma}}{r_e}}S^{\alpha\beta}S^{\alpha\gamma}f_c\left(\frac{r_c-r^{\alpha\beta}}{dr}\right)f_c\left(\frac{r_c-r^{\alpha\gamma}}{dr}\right)
* **radialspin**
.. math::
{}^{rsp}\!S\!f_i^\alpha = \sum_{\beta} \left(\frac{r^{\alpha\beta}}{r_e}\right)^ie^{-\delta_i \frac{r^{\alpha\beta}}{r_e}}\left(\mathbf{s^\alpha \cdot s^\beta}\right)f_c\left(\frac{r_c-r^{\alpha\beta}}{dr}\right)
* **bondspin**
.. math::
{}^{bsp}\!S\!f_{ij}^\alpha = \sum_{\beta}\sum_{\gamma} \left(cos(\theta_{\alpha\beta\gamma})\right)^ie^{-\delta_j \frac{r^{\alpha\beta}}{r_e}}e^{-\delta_j \frac{r^{\alpha\gamma}}{r_e}}\left(\mathbf{s^\alpha \cdot s^\beta}\right)\left(\mathbf{s^\alpha \cdot s^\gamma}\right)f_c\left(\frac{r_c-r^{\alpha\beta}}{dr}\right)f_c\left(\frac{r_c-r^{\alpha\gamma}}{dr}\right)
* **radialscreenedspin**
.. math::
{}^{rscsp}\!S\!f_i^\alpha = \sum_{\beta} \left(\frac{r^{\alpha\beta}}{r_e}\right)^ie^{-\delta_i \frac{r^{\alpha\beta}}{r_e}}S^{\alpha\beta}\left(\mathbf{s^\alpha \cdot s^\beta}\right)f_c\left(\frac{r_c-r^{\alpha\beta}}{dr}\right)
* **bondscreenedspin**
.. math::
{}^{bscsp}\!S\!f_{ij}^\alpha = \sum_{\beta}\sum_{\gamma} \left(cos(\theta_{\alpha\beta\gamma})\right)^ie^{-\delta_j \frac{r^{\alpha\beta}}{r_e}}e^{-\delta_j \frac{r^{\alpha\gamma}}{r_e}}S^{\alpha\beta}S^{\alpha\gamma}\left(\mathbf{s^\alpha \cdot s^\beta}\right)\left(\mathbf{s^\alpha \cdot s^\gamma}\right)f_c\left(\frac{r_c-r^{\alpha\beta}}{dr}\right)f_c\left(\frac{r_c-r^{\alpha\gamma}}{dr}\right)
The activation functions are computed as follows:
.. _activations:
* **sigI**
.. math::
F^{sigI}(x) = 0.1x+0.9ln\left(e^x+1\right)
* **linear**
.. math::
F^{linear}(x) = x
Restrictions
""""""""""""
Pair style *rann* is part of the USER-RANN package. It is only enabled if LAMMPS was built with that
package. Additionally, if any spin fingerprint styles are used LAMMPS must be built with the SPIN
package as well.
Defaults
""""""""""""
Cmin = 0.8, Cmax = 2.8.
----------
.. _Baskes97:
**(Baskes)** Baskes,
Materials Chemistry and Physics, 50(2), 152-158, (1997).
.. _Dickel:
**(Dickel)** Dickel, Francis, and Barrett,
Computational Materials Science 171 (2020): 109157.
.. _Nitol:
**(Nitol)** Nitol, Dickel, and Barrett,
Computational Materials Science 188 (2021): 110207.
.. _Tranchida7:
**(Tranchida)** Tranchida, Plimpton, Thibaudeau and Thompson,
Journal of Computational Physics, 372, 406-425, (2018).

4
doc/src/pair_style.rst
View File

@ -150,6 +150,8 @@ accelerated styles exist.
* :doc:`coul/wolf <pair_coul>` - Coulomb via Wolf potential
* :doc:`coul/wolf/cs <pair_cs>` - Coulomb via Wolf potential with core/shell adjustments
* :doc:`dpd <pair_dpd>` - dissipative particle dynamics (DPD)
* :doc:`dpd/ext <pair_dpd_ext>` - generalized force field for DPD
* :doc:`dpd/ext/tstat <pair_dpd_ext>` - pair-wise DPD thermostatting with generalized force field
* :doc:`dpd/fdt <pair_dpd_fdt>` - DPD for constant temperature and pressure
* :doc:`dpd/fdt/energy <pair_dpd_fdt>` - DPD for constant energy and enthalpy
* :doc:`dpd/tstat <pair_dpd>` - pair-wise DPD thermostatting
@ -180,6 +182,7 @@ accelerated styles exist.
* :doc:`gw/zbl <pair_gw>` - Gao-Weber potential with a repulsive ZBL core
* :doc:`hbond/dreiding/lj <pair_hbond_dreiding>` - DREIDING hydrogen bonding LJ potential
* :doc:`hbond/dreiding/morse <pair_hbond_dreiding>` - DREIDING hydrogen bonding Morse potential
* :doc:`hdnnp <pair_hdnnp>` - High-dimensional neural network potential
* :doc:`ilp/graphene/hbn <pair_ilp_graphene_hbn>` - registry-dependent interlayer potential (ILP)
* :doc:`kim <pair_kim>` - interface to potentials provided by KIM project
* :doc:`kolmogorov/crespi/full <pair_kolmogorov_crespi_full>` - Kolmogorov-Crespi (KC) potential with no simplifications
@ -288,6 +291,7 @@ accelerated styles exist.
* :doc:`polymorphic <pair_polymorphic>` - polymorphic 3-body potential
* :doc:`python <pair_python>` -
* :doc:`quip <pair_quip>` -
* :doc:`rann <pair_rann>` -
* :doc:`reax/c <pair_reaxc>` - ReaxFF potential in C
* :doc:`rebo <pair_airebo>` - second generation REBO potential of Brenner
* :doc:`resquared <pair_resquared>` - Everaers RE-Squared ellipsoidal potential

2
doc/src/pair_thole.rst
View File

@ -42,6 +42,8 @@ Examples
pair_style lj/cut/thole/long 2.6 12.0
Example input scripts available: examples/USER/drude
Description
"""""""""""

3
doc/src/read_data.rst
View File

@ -223,6 +223,9 @@ The structure of the data file is important, though many settings and
sections are optional or can come in any order. See the examples
directory for sample data files for different problems.
The file will be read line by line, but there is a limit of 254
characters per line and characters beyond that limit will be ignored.
A data file has a header and a body. The header appears first. The
first line of the header is always skipped; it typically contains a
description of the file. Then lines are read one at a time. Lines

46
doc/src/thermo_modify.rst
View File

@ -11,12 +11,13 @@ Syntax
thermo_modify keyword value ...
* one or more keyword/value pairs may be listed
* keyword = *lost* or *lost/bond* or *norm* or *flush* or *line* or *format* or *temp* or *press*
* keyword = *lost* or *lost/bond* or *warn* or *norm* or *flush* or *line* or *format* or *temp* or *press*
.. parsed-literal::
*lost* value = *error* or *warn* or *ignore*
*lost/bond* value = *error* or *warn* or *ignore*
*warn* value = *ignore* or *reset* or *default* or a number
*norm* value = *yes* or *no*
*flush* value = *yes* or *no*
*line* value = *one* or *multi*
@ -75,6 +76,43 @@ are drifting out of the box through a fixed boundary condition (see
the :doc:`boundary <boundary>` command). In this case one atom may be
deleted before the rest of the molecule is, on a later timestep.
The *warn* keyword allows you to control whether LAMMPS will print
warning messages and how many of them. Most warning messages are only
printed by MPI rank 0. They are usually pointing out important issues
that should be investigated, but LAMMPS cannot determine for
certain whether they are an indication of an error.
Some warning messages are printed during a run (or immediately before)
each time a specific MPI rank encounters the issue, e.g. bonds that are
stretched too far or dihedrals in extreme configurations. These number
of these can quickly blow up the size of the log file and screen output.
Thus a limit of 100 warning messages is applied by default. The warning
count is applied to the entire input unless reset with a ``thermo_modify
warn reset`` command. If there are more warnings than the limit, LAMMPS
will print one final warning that it will not print any additional
warning messages.
.. note::
The warning limit is enforced on either the per-processor count or
the total count across all processors. For efficiency reasons,
however, the total count is only updated at steps with thermodynamic
output. Thus when running on a large number of processors in
parallel, the total number of warnings printed can be significantly
larger than the given limit.
Any number after the keyword *warn* will change the warning limit
accordingly. With the value *ignore* all warnings will be suppressed,
with the value *always* no limit will be applied and warnings will
always be printed, with the value *reset* the internal warning counter
will be reset to zero, and with the value *default*, the counter is
reset and the limit set to 100. An example usage of either *reset* or
*default* would be to re-enable warnings that were disabled or have
reached the limit during equilibration, where the warnings would be
acceptable while the system is still adjusting, but then change
to all warnings for the production run, where they would indicate
problems that would require a closer look at what is causing them.
The *norm* keyword determines whether various thermodynamic output
values are normalized by the number of atoms or not, depending on
whether it is set to *yes* or *no*\ . Different unit styles have
@ -183,9 +221,9 @@ Related commands
Default
"""""""
The option defaults are lost = error, norm = yes for unit style of
*lj*\ , norm = no for unit style of *real* and *metal*\ , flush = no,
and temp/press = compute IDs defined by thermo_style.
The option defaults are lost = error, warn = 100, norm = yes for unit
style of *lj*\ , norm = no for unit style of *real* and *metal*\ ,
flush = no, and temp/press = compute IDs defined by thermo_style.
The defaults for the line and format options depend on the thermo
style. For styles "one" and "custom", the line and format defaults

14
doc/src/variable.rst
View File

@ -363,12 +363,14 @@ variable, as discussed below.
The rules for formatting the file are as follows. Each time a set of
per-atom values is read, a non-blank line is searched for in the file.
A comment character "#" can be used anywhere on a line; text starting
with the comment character is stripped. Blank lines are skipped. The
first "word" of a non-blank line, delimited by white-space, is read as
the count N of per-atom lines to immediately follow. N can be the
total number of atoms in the system, or only a subset. The next N
lines have the following format
The file is read line by line but only up to 254 characters are used.
The rest are ignored. A comment character "#" can be used anywhere
on a line and all text following and the "#" character are ignored;
text starting with the comment character is stripped. Blank lines
are skipped. The first "word" of a non-blank line, delimited by
white-space, is read as the count N of per-atom lines to immediately
follow. N can be the total number of atoms in the system, or only a
subset. The next N lines have the following format
.. parsed-literal::