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

Fix merge conflicts

Browse Source
This commit is contained in:
rohskopf
2022-11-07 17:37:50 -07:00
parent 1fbd45a05d 9cbc77f41c
commit da929b4f7f
4702 changed files with 83803 additions and 43475 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
doc/src/Bibliography.rst
View File

@ -314,7 +314,7 @@ Bibliography
Espanol, Revenga, Physical Review E, 67, 026705 (2003).
**(Espanol1997)**
Espanol, Europhys Lett, 40(6): 631-636 (1997). DOI: 10.1209/epl/i1997-00515-8
Espanol, Europhys Lett, 40(6): 631-636 (1997). DOI:10.1209/epl/i1997-00515-8
**(Evans and Morriss)**
Evans and Morriss, Phys Rev A, 30, 1528 (1984).
@ -368,7 +368,7 @@ Bibliography
Frenkel and Smit, Understanding Molecular Simulation, Academic Press, London, 2002.
**(GLE4MD)**
`http://gle4md.org/ <http://gle4md.org/>`_
`https://gle4md.org/ <https://gle4md.org/>`_
**(Gao)**
Gao and Weber, Nuclear Instruments and Methods in Physics Research B 191 (2012) 504.
@ -401,13 +401,13 @@ Bibliography
Hayre, and Farago, Comp Phys Comm, 185, 524 (2014)
**(Groot)**
Groot and Warren, J Chem Phys, 107: 4423-4435 (1997). DOI: 10.1063/1.474784
Groot and Warren, J Chem Phys, 107: 4423-4435 (1997). DOI:10.1063/1.474784
**(Guenole)**
Guenole, Noehring, Vaid, Houlle, Xie, Prakash, Bitzek, Comput Mater Sci, 175, 109584 (2020).
**(Gullet)**
Gullet, Wagner, Slepoy, SANDIA Report 2003-8782 (2003).
Gullet, Wagner, Slepoy, SANDIA Report 2003-8782 (2003). DOI:10.2172/918395
**(Guo)**
Guo and Thirumalai, Journal of Molecular Biology, 263, 323-43 (1996).
@ -461,7 +461,7 @@ Bibliography
Hunt, Mol Simul, 42, 347 (2016).
**(IPI)**
`http://epfl-cosmo.github.io/gle4md/index.html?page=ipi <http://epfl-cosmo.github.io/gle4md/index.html?page=ipi>`_
`https://ipi-code.org/ <https://ipi-code.org/>`
**(IPI-CPC)**
Ceriotti, More and Manolopoulos, Comp Phys Comm, 185, 1019-1026 (2014).
@ -605,16 +605,16 @@ Bibliography
I.\ Leven et al, J. Chem.Theory Comput. 12, 2896-905 (2016).
**(Li2013_POF)**
Li, Hu, Wang, Ma, Zhou, Phys Fluids, 25: 072103 (2013). DOI: 10.1063/1.4812366.
Li, Hu, Wang, Ma, Zhou, Phys Fluids, 25: 072103 (2013). DOI:10.1063/1.4812366.
**(Li2014_JCP)**
Li, Tang, Lei, Caswell, Karniadakis, J Comput Phys, 265: 113-127 (2014). DOI: 10.1016/j.jcp.2014.02.003.
Li, Tang, Lei, Caswell, Karniadakis, J Comput Phys, 265: 113-127 (2014). DOI:10.1016/j.jcp.2014.02.003.
**(Li2015_CC)**
Li, Tang, Li, Karniadakis, Chem Commun, 51: 11038-11040 (2015). DOI: 10.1039/C5CC01684C.
Li, Tang, Li, Karniadakis, Chem Commun, 51: 11038-11040 (2015). DOI:10.1039/C5CC01684C.
**(Li2015_JCP)**
Li, Yazdani, Tartakovsky, Karniadakis, J Chem Phys, 143: 014101 (2015). DOI: 10.1063/1.4923254.
Li, Yazdani, Tartakovsky, Karniadakis, J Chem Phys, 143: 014101 (2015). DOI:10.1063/1.4923254.
**(Lisal)**
M.\ Lisal, J.K. Brennan, J. Bonet Avalos, "Dissipative particle dynamics at isothermal, isobaric, isoenergetic, and isoenthalpic conditions using Shardlow-like splitting algorithms.",
@ -733,8 +733,8 @@ Bibliography
**(Mishin)**
Mishin, Mehl, and Papaconstantopoulos, Acta Mater, 53, 4029 (2005).
**(Mitchell and Finchham)**
Mitchell, Finchham, J Phys Condensed Matter, 5, 1031-1038 (1993).
**(Mitchell and Fincham)**
Mitchell, Fincham, J Phys Condensed Matter, 5, 1031-1038 (1993).
**(Mitchell2011)**
Mitchell. A non-local, ordinary-state-based viscoelasticity model for peridynamics. Sandia National Lab Report, 8064:1-28 (2011).
@ -875,7 +875,7 @@ Bibliography
G.A. Tribello, M. Bonomi, D. Branduardi, C. Camilloni and G. Bussi, Comp. Phys. Comm 185, 604 (2014)
**(Paquay)**
Paquay and Kusters, Biophys. J., 110, 6, (2016). preprint available at `arXiv:1411.3019 <http://arxiv.org/abs/1411.3019/>`_.
Paquay and Kusters, Biophys. J., 110, 6, (2016). preprint available at `arXiv:1411.3019 <https://arxiv.org/abs/1411.3019/>`_.
**(Park)**
Park, Schulten, J. Chem. Phys. 120 (13), 5946 (2004)

12
doc/src/Build_development.rst
View File

@ -140,13 +140,23 @@ of the LAMMPS project on GitHub.
The unit testing facility is integrated into the CMake build process
of the LAMMPS source code distribution itself. It can be enabled by
setting ``-D ENABLE_TESTING=on`` during the CMake configuration step.
It requires the `YAML <http://pyyaml.org/>`_ library and development
It requires the `YAML <https://pyyaml.org/>`_ library and development
headers (if those are not found locally a recent version will be
downloaded and compiled along with LAMMPS and the test program) to
compile and will download and compile a specific recent version of the
`Googletest <https://github.com/google/googletest/>`_ C++ test framework
for implementing the tests.
.. admonition:: Software version requirements for testing
:class: note
The compiler and library version requirements for the testing
framework are more strict than for the main part of LAMMPS. For
example the default GNU C++ and Fortran compilers of RHEL/CentOS 7.x
(version 4.8.x) are not sufficient. The CMake configuration will try
to detect compatible versions and either skip incompatible tests or
stop with an error.
After compilation is complete, the unit testing is started in the build
folder using the ``ctest`` command, which is part of the CMake software.
The output of this command will be looking something like this::

94
doc/src/Build_extras.rst
View File

@ -234,7 +234,7 @@ LAMMPS code. This also applies to the ``-DLAMMPS_BIGBIG``\ ,
Makefile you use.
You can also build the library in one step from the ``lammps/src`` dir,
using a command like these, which simply invoke the ``lib/gpu/Install.py``
using a command like these, which simply invokes the ``lib/gpu/Install.py``
script with the specified args:
.. code-block:: bash
@ -314,7 +314,7 @@ detailed information is available at:
In addition to installing the KIM API, it is also necessary to install the
library of KIM models (interatomic potentials).
See `Obtaining KIM Models <http://openkim.org/doc/usage/obtaining-models>`_ to
See `Obtaining KIM Models <https://openkim.org/doc/usage/obtaining-models>`_ to
learn how to install a pre-build binary of the OpenKIM Repository of Models.
See the list of all KIM models here: https://openkim.org/browse/models
@ -350,7 +350,7 @@ minutes to hours) to build. Of course you only need to do that once.)
You can download and build the KIM library manually if you prefer;
follow the instructions in ``lib/kim/README``. You can also do
this in one step from the lammps/src directory, using a command like
these, which simply invoke the ``lib/kim/Install.py`` script with
these, which simply invokes the ``lib/kim/Install.py`` script with
the specified args.
.. code-block:: bash
@ -432,7 +432,7 @@ Enabling the extra unit tests have some requirements,
``EAM_Dynamo_MendelevAckland_2007v3_Zr__MO_004835508849_000``,
``EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005``, and
``LennardJones612_UniversalShifted__MO_959249795837_003`` KIM models.
See `Obtaining KIM Models <http://openkim.org/doc/usage/obtaining-models>`_
See `Obtaining KIM Models <https://openkim.org/doc/usage/obtaining-models>`_
to learn how to install a pre-built binary of the OpenKIM Repository of
Models or see
`Installing KIM Models <https://openkim.org/doc/usage/obtaining-models/#installing_models>`_
@ -483,6 +483,9 @@ They must be specified in uppercase.
* - **Arch-ID**
- **HOST or GPU**
- **Description**
* - NATIVE
- HOST
- Local machine
* - AMDAVX
- HOST
- AMD 64-bit x86 CPU (AVX 1)
@ -522,9 +525,21 @@ They must be specified in uppercase.
* - BDW
- HOST
- Intel Broadwell Xeon E-class CPU (AVX 2 + transactional mem)
* - SKL
- HOST
- Intel Skylake Client CPU
* - SKX
- HOST
- Intel Sky Lake Xeon E-class HPC CPU (AVX512 + transactional mem)
- Intel Skylake Xeon Server CPU (AVX512)
* - ICL
- HOST
- Intel Ice Lake Client CPU (AVX512)
* - ICX
- HOST
- Intel Ice Lake Xeon Server CPU (AVX512)
* - SPR
- HOST
- Intel Sapphire Rapids Xeon Server CPU (AVX512)
* - KNC
- HOST
- Intel Knights Corner Xeon Phi
@ -596,7 +611,10 @@ They must be specified in uppercase.
- AMD GPU MI100 GFX908
* - VEGA90A
- GPU
- AMD GPU
- AMD GPU MI200 GFX90A
* - INTEL_GEN
- GPU
- SPIR64-based devices, e.g. Intel GPUs, using JIT
* - INTEL_DG1
- GPU
- Intel Iris XeMAX GPU
@ -611,9 +629,12 @@ They must be specified in uppercase.
- Intel GPU Gen12LP
* - INTEL_XEHP
- GPU
- Intel GPUs Xe-HP
- Intel GPU Xe-HP
* - INTEL_PVC
- GPU
- Intel GPU Ponte Vecchio
This list was last updated for version 3.5.0 of the Kokkos library.
This list was last updated for version 3.7.0 of the Kokkos library.
.. tabs::
@ -933,7 +954,7 @@ more details.
You can download and build the MS-CG library manually if you
prefer; follow the instructions in ``lib/mscg/README``\ . You can
also do it in one step from the ``lammps/src`` dir, using a
command like these, which simply invoke the
command like these, which simply invokes the
``lib/mscg/Install.py`` script with the specified args:
.. code-block:: bash
@ -990,7 +1011,7 @@ POEMS package
``lib/poems``\ . You can do this manually if you prefer; follow
the instructions in ``lib/poems/README``\ . You can also do it in
one step from the ``lammps/src`` dir, using a command like these,
which simply invoke the ``lib/poems/Install.py`` script with the
which simply invokes the ``lib/poems/Install.py`` script with the
specified args:
.. code-block:: bash
@ -1053,7 +1074,7 @@ VORONOI package
-----------------------------
To build with this package, you must download and build the
`Voro++ library <http://math.lbl.gov/voro++>`_ or install a
`Voro++ library <https://math.lbl.gov/voro++>`_ or install a
binary package provided by your operating system.
.. tabs::
@ -1079,7 +1100,7 @@ binary package provided by your operating system.
You can download and build the Voro++ library manually if you
prefer; follow the instructions in ``lib/voronoi/README``. You
can also do it in one step from the ``lammps/src`` dir, using a
command like these, which simply invoke the
command like these, which simply invokes the
``lib/voronoi/Install.py`` script with the specified args:
.. code-block:: bash
@ -1158,7 +1179,7 @@ The ATC package requires the MANYBODY package also be installed.
``lib/atc``. You can do this manually if you prefer; follow the
instructions in ``lib/atc/README``. You can also do it in one
step from the ``lammps/src`` dir, using a command like these,
which simply invoke the ``lib/atc/Install.py`` script with the
which simply invokes the ``lib/atc/Install.py`` script with the
specified args:
.. code-block:: bash
@ -1209,7 +1230,7 @@ AWPMD package
``lib/awpmd``. You can do this manually if you prefer; follow the
instructions in ``lib/awpmd/README``. You can also do it in one
step from the ``lammps/src`` dir, using a command like these,
which simply invoke the ``lib/awpmd/Install.py`` script with the
which simply invokes the ``lib/awpmd/Install.py`` script with the
specified args:
.. code-block:: bash
@ -1272,7 +1293,7 @@ be built for the most part with all major versions of the C++ language.
In general, it is safer to use build setting consistent with the
rest of LAMMPS. This is best carried out from the LAMMPS src
directory using a command like these, which simply invoke the
directory using a command like these, which simply invokes the
``lib/colvars/Install.py`` script with the specified args:
.. code-block:: bash
@ -1313,20 +1334,30 @@ This package depends on the KSPACE package.
.. tab:: CMake build
No additional settings are needed besides ``-D PKG_KSPACE=yes`` and ``-D
PKG_ELECTRODE=yes``.
No additional settings are needed besides ``-D PKG_KSPACE=yes`` and
``-D PKG_ELECTRODE=yes``.
.. tab:: Traditional make
The package is activated with ``make yes-KSPACE`` and ``make
yes-ELECTRODE``
Before building LAMMPS, you must configure the ELECTRODE support
libraries and settings in ``lib/electrode``. You can do this
manually, if you prefer, or do it in one step from the
``lammps/src`` dir, using a command like these, which simply
invokes the ``lib/electrode/Install.py`` script with the specified
args:
.. code-block:: bash
$ make lib-electrode # print help message
$ make lib-electrode args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
$ make lib-electrode args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
Note that the ``Makefile.lammps`` file has settings for the BLAS and
LAPACK linear algebra libraries. As explained in ``lib/awpmd/README``
these can either exist on your system, or you can use the files provided
in ``lib/linalg``. In the latter case you also need to build the library
in ``lib/linalg`` with a command like these:
Note that the ``Makefile.lammps`` file has settings for the BLAS
and LAPACK linear algebra libraries. These can either exist on
your system, or you can use the files provided in ``lib/linalg``.
In the latter case you also need to build the library in
``lib/linalg`` with a command like these:
.. code-block:: bash
@ -1335,6 +1366,9 @@ This package depends on the KSPACE package.
$ make lib-linalg args="-m mpi" # build with default MPI Fortran compiler (settings as with "make mpi")
$ make lib-linalg args="-m gfortran" # build with GNU Fortran compiler
The package itself is activated with ``make yes-KSPACE`` and
``make yes-ELECTRODE``
----------
.. _ml-pace:
@ -1534,7 +1568,7 @@ the HDF5 library.
``lib/h5md``. You can do this manually if you prefer; follow the
instructions in ``lib/h5md/README``. You can also do it in one
step from the ``lammps/src`` dir, using a command like these,
which simply invoke the ``lib/h5md/Install.py`` script with the
which simply invokes the ``lib/h5md/Install.py`` script with the
specified args:
.. code-block:: bash
@ -1590,7 +1624,7 @@ details please see ``lib/hdnnp/README`` and the `n2p2 build documentation
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:
simply invokes the ``lib/hdnnp/Install.py`` script with the specified args:
.. code-block:: bash
@ -1727,7 +1761,7 @@ they will be downloaded the first time this package is installed.
Before building LAMMPS, you must build the *mesont* library in
``lib/mesont``\ . You can also do it in one step from the
``lammps/src`` dir, using a command like these, which simply
invoke the ``lib/mesont/Install.py`` script with the specified
invokes the ``lib/mesont/Install.py`` script with the specified
args:
.. code-block:: bash
@ -1896,7 +1930,7 @@ verified to work in February 2020 with Quantum Espresso versions 6.3 to
``lib/qmmm``. You can do this manually if you prefer; follow the
first two steps explained in ``lib/qmmm/README``. You can also do
it in one step from the ``lammps/src`` dir, using a command like
these, which simply invoke the ``lib/qmmm/Install.py`` script with
these, which simply invokes the ``lib/qmmm/Install.py`` script with
the specified args:
.. code-block:: bash
@ -2004,7 +2038,7 @@ To build with this package, you must download and build the
You can download and build the ScaFaCoS library manually if you
prefer; follow the instructions in ``lib/scafacos/README``. You
can also do it in one step from the ``lammps/src`` dir, using a
command like these, which simply invoke the
command like these, which simply invokes the
``lib/scafacos/Install.py`` script with the specified args:
.. code-block:: bash
@ -2048,7 +2082,7 @@ Eigen3 is a template library, so you do not need to build it.
You can download the Eigen3 library manually if you prefer; follow
the instructions in ``lib/smd/README``. You can also do it in one
step from the ``lammps/src`` dir, using a command like these,
which simply invoke the ``lib/smd/Install.py`` script with the
which simply invokes the ``lib/smd/Install.py`` script with the
specified args:
.. code-block:: bash

19
doc/src/Build_manual.rst
View File

@ -176,7 +176,7 @@ math expressions transparently into embedded images.
For converting the generated ePUB file to a MOBI format file (for e-book
readers, like Kindle, that cannot read ePUB), you also need to have the
``ebook-convert`` tool from the "calibre" software
installed. `http://calibre-ebook.com/ <http://calibre-ebook.com/>`_
installed. `https://calibre-ebook.com/ <https://calibre-ebook.com/>`_
Typing ``make mobi`` will first create the ePUB file and then convert
it. On the Kindle readers in particular, you also have support for PDF
files, so you could download and view the PDF version as an alternative.
@ -216,9 +216,20 @@ be multiple tests run automatically:
- A test that only standard, printable ASCII text characters are used.
This runs the command ``env LC_ALL=C grep -n '[^ -~]' src/*.rst`` and
thus prints all offending lines with filename and line number
prepended to the screen. Special characters like the Angstrom
:math:`\mathrm{\mathring{A}}` should be typeset with embedded math
(like this ``:math:`\mathrm{\mathring{A}}```\ ).
prepended to the screen. Special characters like Greek letters
(:math:`\alpha~~\sigma~~\epsilon`), super- or subscripts
(:math:`x^2~~\mathrm{U}_{LJ}`), mathematical expressions
(:math:`\frac{1}{2}\mathrm{N}~~x\to\infty`), or the Angstrom symbol
(:math:`\AA`) should be typeset with embedded LaTeX (like this
``:math:`\alpha \sigma \epsilon```, ``:math:`x^2 \mathrm{E}_{LJ}```,
``:math:`\frac{1}{2}\mathrm{N} x\to\infty```, or ``:math:`\AA```\ ).
- Embedded LaTeX is rendered in HTML output with `MathJax
<https://www.mathjax.org/>`_ and in PDF output by passing the embedded
text to LaTeX. Some care has to be taken, though, since there are
limitations which macros and features can be used in either mode, so
it is recommended to always check whether any new or changed
documentation does translate and render correctly with either output.
- A test whether all styles are documented and listed in their
respective overview pages. A typical output with warnings looks like this:

29
doc/src/Build_settings.rst
View File

@ -111,26 +111,25 @@ LAMMPS can use them if they are available on your system.
files in its default search path. You must specify ``FFT_LIB``
with the appropriate FFT libraries to include in the link.
The `KISS FFT library <http://kissfft.sf.net>`_ is included in the LAMMPS
distribution. It is portable across all platforms. Depending on the size
of the FFTs and the number of processors used, the other libraries listed
here can be faster.
The `KISS FFT library <https://github.com/mborgerding/kissfft>`_ is
included in the LAMMPS distribution. It is portable across all
platforms. Depending on the size of the FFTs and the number of
processors used, the other libraries listed here can be faster.
However, note that long-range Coulombics are only a portion of the
per-timestep CPU cost, FFTs are only a portion of long-range
Coulombics, and 1d FFTs are only a portion of the FFT cost (parallel
communication can be costly). A breakdown of these timings is printed
to the screen at the end of a run when using the
:doc:`kspace_style pppm <kspace_style>` command. The
:doc:`Screen and logfile output <Run_output>`
page gives more details. A more detailed (and time consuming)
report of the FFT performance is generated with the
per-timestep CPU cost, FFTs are only a portion of long-range Coulombics,
and 1d FFTs are only a portion of the FFT cost (parallel communication
can be costly). A breakdown of these timings is printed to the screen
at the end of a run when using the :doc:`kspace_style pppm
<kspace_style>` command. The :doc:`Screen and logfile output
<Run_output>` page gives more details. A more detailed (and time
consuming) report of the FFT performance is generated with the
:doc:`kspace_modify fftbench yes <kspace_modify>` command.
FFTW is a fast, portable FFT library that should also work on any
platform and can be faster than the KISS FFT library. You can
download it from `www.fftw.org <http://www.fftw.org>`_. LAMMPS requires
version 3.X; the legacy version 2.1.X is no longer supported.
platform and can be faster than the KISS FFT library. You can download
it from `www.fftw.org <https://www.fftw.org>`_. LAMMPS requires version
3.X; the legacy version 2.1.X is no longer supported.
Building FFTW for your box should be as simple as ``./configure; make;
make install``. The install command typically requires root privileges

4
doc/src/Commands_pair.rst
View File

@ -205,7 +205,7 @@ OPT.
* :doc:`mesont/tpm <pair_mesont_tpm>`
* :doc:`mgpt <pair_mgpt>`
* :doc:`mie/cut (g) <pair_mie>`
* :doc:`mliap <pair_mliap>`
* :doc:`mliap (k) <pair_mliap>`
* :doc:`mm3/switch3/coulgauss/long <pair_lj_switch3_coulgauss_long>`
* :doc:`momb <pair_momb>`
* :doc:`morse (gkot) <pair_morse>`
@ -236,6 +236,7 @@ OPT.
* :doc:`oxrna2/xstk <pair_oxrna2>`
* :doc:`oxrna2/coaxstk <pair_oxrna2>`
* :doc:`pace (k) <pair_pace>`
* :doc:`pace/extrapolation <pair_pace>`
* :doc:`pod <pair_pod>`
* :doc:`peri/eps <pair_peri>`
* :doc:`peri/lps (o) <pair_peri>`
@ -295,6 +296,7 @@ OPT.
* :doc:`vashishta (gko) <pair_vashishta>`
* :doc:`vashishta/table (o) <pair_vashishta>`
* :doc:`wf/cut <pair_wf_cut>`
* :doc:`ylz <pair_ylz>`
* :doc:`yukawa (gko) <pair_yukawa>`
* :doc:`yukawa/colloid (go) <pair_yukawa_colloid>`
* :doc:`zbl (gko) <pair_zbl>`

2
doc/src/Developer_updating.rst
View File

@ -7,7 +7,7 @@ source files provided as a supplement to a publication) that are written
for an older version of LAMMPS and thus need to be updated to be
compatible with the current version of LAMMPS. Due to the active
development of LAMMPS it is likely to always be incomplete. Please
contact developer@lammps.org in case you run across an issue that is not
contact developers@lammps.org in case you run across an issue that is not
(yet) listed here. Please also review the latest information about the
LAMMPS :doc:`programming style conventions <Modify_style>`, especially
if you are considering to submit the updated version for inclusion into

2
doc/src/Errors_debug.rst
View File

@ -75,7 +75,7 @@ Using the GDB debugger to get a stack trace
There are two options to use the GDB debugger for identifying the origin
of the segmentation fault or similar crash. The GDB debugger has many
more features and options, as can be seen for example its `online
documentation <http://sourceware.org/gdb/current/onlinedocs/gdb/>`_.
documentation <https://sourceware.org/gdb/current/onlinedocs/gdb/>`_.
Run LAMMPS from within the debugger
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

2085
doc/src/Fortran.rst
View File

File diff suppressed because it is too large Load Diff

1
doc/src/Howto.rst
View File

@ -85,6 +85,7 @@ Packages howto
Howto_coreshell
Howto_drude
Howto_drude2
Howto_peri
Howto_manifold
Howto_spins

2
doc/src/Howto_amoeba.rst
View File

@ -281,7 +281,7 @@ Here is more information about the extended XYZ format defined and
used by Tinker, and links to programs that convert standard PDB files
to the extended XYZ format:
* `http://openbabel.org/docs/current/FileFormats/Tinker_XYZ_format.html <http://openbabel.org/docs/current/FileFormats/Tinker_XYZ_format.html>`_
* `https://openbabel.org/docs/current/FileFormats/Tinker_XYZ_format.html <https://openbabel.org/docs/current/FileFormats/Tinker_XYZ_format.html>`_
* `https://github.com/emleddin/pdbxyz-xyzpdb <https://github.com/emleddin/pdbxyz-xyzpdb>`_
* `https://github.com/TinkerTools/tinker/blob/release/source/pdbxyz.f <https://github.com/TinkerTools/tinker/blob/release/source/pdbxyz.f>`_

33
doc/src/Howto_bioFF.rst
View File

@ -3,24 +3,20 @@ CHARMM, AMBER, COMPASS, and DREIDING force fields
A force field has 2 parts: the formulas that define it and the
coefficients used for a particular system. Here we only discuss
formulas implemented in LAMMPS that correspond to formulas commonly
used in the CHARMM, AMBER, COMPASS, and DREIDING force fields. Setting
formulas implemented in LAMMPS that correspond to formulas commonly used
in the CHARMM, AMBER, COMPASS, and DREIDING force fields. Setting
coefficients is done either from special sections in an input data file
via the :doc:`read_data <read_data>` command or in the input script with
commands like :doc:`pair_coeff <pair_coeff>` or
:doc:`bond_coeff <bond_coeff>` and so on. See the :doc:`Tools <Tools>` doc
page for additional tools that can use CHARMM, AMBER, or Materials
Studio generated files to assign force field coefficients and convert
their output into LAMMPS input.
commands like :doc:`pair_coeff <pair_coeff>` or :doc:`bond_coeff
<bond_coeff>` and so on. See the :doc:`Tools <Tools>` doc page for
additional tools that can use CHARMM, AMBER, or Materials Studio
generated files to assign force field coefficients and convert their
output into LAMMPS input.
See :ref:`(MacKerell) <howto-MacKerell>` for a description of the CHARMM force
field. See :ref:`(Cornell) <howto-Cornell>` for a description of the AMBER
force field. See :ref:`(Sun) <howto-Sun>` for a description of the COMPASS
force field.
.. _charmm: http://www.scripps.edu/brooks
.. _amber: http://amber.scripps.edu
See :ref:`(MacKerell) <howto-MacKerell>` for a description of the CHARMM
force field. See :ref:`(Cornell) <howto-Cornell>` for a description of
the AMBER force field. See :ref:`(Sun) <howto-Sun>` for a description
of the COMPASS force field.
The interaction styles listed below compute force field formulas that
are consistent with common options in CHARMM or AMBER. See each
@ -41,9 +37,10 @@ command's documentation for the formula it computes.
.. note::
For CHARMM, newer *charmmfsw* or *charmmfsh* styles were released
in March 2017. We recommend they be used instead of the older *charmm*
styles. See discussion of the differences on the :doc:`pair charmm <pair_charmm>` and :doc:`dihedral charmm <dihedral_charmm>` doc
For CHARMM, newer *charmmfsw* or *charmmfsh* styles were released in
March 2017. We recommend they be used instead of the older *charmm*
styles. See discussion of the differences on the :doc:`pair charmm
<pair_charmm>` and :doc:`dihedral charmm <dihedral_charmm>` doc
pages.
COMPASS is a general force field for atomistic simulation of common

113
doc/src/Howto_bpm.rst
View File

@ -33,46 +33,6 @@ reference state of a bond. Bonds that are created midway into a run,
such as those created by pouring grains using :doc:`fix pour
<fix_pour>`, are initialized on that timestep.
As bonds can be broken between neighbor list builds, the
:doc:`special_bonds <special_bonds>` command works differently for BPM
bond styles. There are two possible settings which determine how pair
interactions work between bonded particles. First, one can turn off
all pair interactions between bonded particles. Unlike :doc:`bond
quartic <bond_quartic>`, this is not done by subtracting pair forces
during the bond computation but rather by dynamically updating the
special bond list. This is the default behavior of BPM bond styles and
is done by updating the 1-2 special bond list as bonds break. To do
this, LAMMPS requires :doc:`newton <newton>` bond off such that all
processors containing an atom know when a bond breaks. Additionally,
one must do either (A) or (B).
A) Use the following special bond settings
.. code-block:: LAMMPS
special_bonds lj 0 1 1 coul 1 1 1
These settings accomplish two goals. First, they turn off 1-3 and 1-4
special bond lists, which are not currently supported for BPMs. As
BPMs often have dense bond networks, generating 1-3 and 1-4 special
bond lists is expensive. By setting the lj weight for 1-2 bonds to
zero, this turns off pairwise interactions. Even though there are no
charges in BPM models, setting a nonzero coul weight for 1-2 bonds
ensures all bonded neighbors are still included in the neighbor list
in case bonds break between neighbor list builds.
B) Alternatively, one can simply overlay pair interactions such that all
bonded particles also feel pair interactions. This can be
accomplished by using the *overlay/pair* keyword present in all bpm
bond styles and by using the following special bond settings
.. code-block:: LAMMPS
special_bonds lj/coul 1 1 1
See the :doc:`Howto <Howto_broken_bonds>` page on broken bonds for
more information.
----------
Currently there are two types of bonds included in the BPM
@ -91,12 +51,6 @@ This also requires a unique integrator :doc:`fix nve/bpm/sphere
<fix_nve_bpm_sphere>` which numerically integrates orientation similar
to :doc:`fix nve/asphere <fix_nve_asphere>`.
To monitor the fracture of bonds in the system, all BPM bond styles
have the ability to record instances of bond breakage to output using
the :doc:`dump local <dump>` command. Additionally, one can use
:doc:`compute nbond/atom <compute_nbond_atom>` to tally the current
number of bonds per atom.
In addition to bond styles, a new pair style :doc:`pair bpm/spring
<pair_bpm_spring>` was added to accompany the bpm/spring bond
style. This pair style is simply a hookean repulsion with similar
@ -104,6 +58,73 @@ velocity damping as its sister bond style.
----------
Bond data can be output using a combination of standard LAMMPS commands.
A list of IDs for bonded atoms can be generated using the
:doc:`compute property/local <compute_property_local>` command.
Various properties of bonds can be computed using the
:doc:`compute bond/local <compute_bond_local>` command. This
command allows one to access data saved to the bond's history
such as the reference length of the bond. More information on
bond history data can be found on the documentation pages for the specific
BPM bond styles. Finally, this data can be output using a :doc:`dump local <dump>`
command. As one may output many columns from the same compute, the
:doc:`dump modify <dump_modify>` *colname* option may be used to provide
more helpful column names. An example of this procedure is found in
/examples/bpm/pour/. External software, such as OVITO, can read these dump
files to render bond data.
----------
As bonds can be broken between neighbor list builds, the
:doc:`special_bonds <special_bonds>` command works differently for BPM
bond styles. There are two possible settings which determine how pair
interactions work between bonded particles. First, one can overlay
pair forces with bond forces such that all bonded particles also
feel pair interactions. This can be accomplished by using the *overlay/pair*
keyword present in all bpm bond styles and by using the following special
bond settings
.. code-block:: LAMMPS
special_bonds lj/coul 1 1 1
Alternatively, one can turn off all pair interactions between bonded
particles. Unlike :doc:`bond quartic <bond_quartic>`, this is not done
by subtracting pair forces during the bond computation but rather by
dynamically updating the special bond list. This is the default behavior
of BPM bond styles and is done by updating the 1-2 special bond list as
bonds break. To do this, LAMMPS requires :doc:`newton <newton>` bond off
such that all processors containing an atom know when a bond breaks.
Additionally, one must use the following special bond settings
.. code-block:: LAMMPS
special_bonds lj 0 1 1 coul 1 1 1
These settings accomplish two goals. First, they turn off 1-3 and 1-4
special bond lists, which are not currently supported for BPMs. As
BPMs often have dense bond networks, generating 1-3 and 1-4 special
bond lists is expensive. By setting the lj weight for 1-2 bonds to
zero, this turns off pairwise interactions. Even though there are no
charges in BPM models, setting a nonzero coul weight for 1-2 bonds
ensures all bonded neighbors are still included in the neighbor list
in case bonds break between neighbor list builds.
To monitor the fracture of bonds in the system, all BPM bond styles
have the ability to record instances of bond breakage to output using
the :doc:`dump local <dump>` command. Since one may frequently output
a list of broken bonds and the time they broke, the
:doc:`dump modify <dump_modify>` option *header no* may be useful to
avoid repeatedly printing the header of the dump file. An example of
this procedure is found in /examples/bpm/impact/. Additionally,
one can use :doc:`compute nbond/atom <compute_nbond_atom>` to tally the
current number of bonds per atom.
See the :doc:`Howto <Howto_broken_bonds>` page on broken bonds for
more information.
----------
While LAMMPS has many utilities to create and delete bonds, *only*
the following are currently compatible with BPM bond styles:

2
doc/src/Howto_github.rst
View File

@ -10,7 +10,7 @@ changes or additions you have made to LAMMPS into the official LAMMPS
distribution. It uses the process of updating this very tutorial as an
example to describe the individual steps and options. You need to be
familiar with git and you may want to have a look at the `git book
<http://git-scm.com/book/>`_ to familiarize yourself with some of the
<https://git-scm.com/book/>`_ to familiarize yourself with some of the
more advanced git features used below.
As of fall 2016, submitting contributions to LAMMPS via pull requests

2
doc/src/Howto_manifold.rst
View File

@ -47,4 +47,4 @@ to the relevant fixes.
.. _Paquay1:
**(Paquay)** Paquay and Kusters, Biophys. J., 110, 6, (2016).
preprint available at `arXiv:1411.3019 <http://arxiv.org/abs/1411.3019/>`_.
preprint available at `arXiv:1411.3019 <https://arxiv.org/abs/1411.3019/>`_.

1078
doc/src/Howto_peri.rst Normal file
View File

File diff suppressed because it is too large Load Diff

2
doc/src/Howto_spc.rst
View File

@ -38,7 +38,7 @@ the partial charge assignments change:
See the :ref:`(Berendsen) <howto-Berendsen>` reference for more details on both
the SPC and SPC/E models.
Wikipedia also has a nice article on `water models <http://en.wikipedia.org/wiki/Water_model>`_.
Wikipedia also has a nice article on `water models <https://en.wikipedia.org/wiki/Water_model>`_.
----------

16
doc/src/Howto_spins.rst
View File

@ -30,9 +30,11 @@ can be coupled to another Langevin thermostat applied to the atoms
using :doc:`fix langevin <fix_langevin>` in order to simulate
thermostatted spin-lattice systems.
The magnetic Gilbert damping can also be applied using :doc:`fix langevin/spin <fix_langevin_spin>`. It allows to either dissipate
the thermal energy of the Langevin thermostat, or to perform a
relaxation of the magnetic configuration toward an equilibrium state.
The magnetic damping can also be applied
using :doc:`fix langevin/spin <fix_langevin_spin>`.
It allows to either dissipate the thermal energy of the Langevin
thermostat, or to perform a relaxation of the magnetic configuration
toward an equilibrium state.
The command :doc:`fix setforce/spin <fix_setforce>` allows to set the
components of the magnetic precession vectors (while erasing and
@ -52,9 +54,11 @@ All the computed magnetic properties can be output by two main
commands. The first one is :doc:`compute spin <compute_spin>`, that
enables to evaluate magnetic averaged quantities, such as the total
magnetization of the system along x, y, or z, the spin temperature, or
the magnetic energy. The second command is :doc:`compute property/atom <compute_property_atom>`. It enables to output all the
per atom magnetic quantities. Typically, the orientation of a given
magnetic spin, or the magnetic force acting on this spin.
the magnetic energy. The second command
is :doc:`compute property/atom <compute_property_atom>`.
It enables to output all the per atom magnetic quantities. Typically,
the orientation of a given magnetic spin, or the magnetic force
acting on this spin.
----------

2
doc/src/Howto_tip3p.rst
View File

@ -49,7 +49,7 @@ details:
| :math:`\theta` of HOH angle = 104.52\ :math:`^{\circ}`
|
Wikipedia also has a nice article on `water models <http://en.wikipedia.org/wiki/Water_model>`_.
Wikipedia also has a nice article on `water models <https://en.wikipedia.org/wiki/Water_model>`_.
----------

39
doc/src/Howto_tip4p.rst
View File

@ -8,18 +8,28 @@ This site M is located at a fixed distance away from the oxygen along
the bisector of the HOH bond angle. A bond style of *harmonic* and an
angle style of *harmonic* or *charmm* should also be used.
A TIP4P model is run with LAMMPS using either this command
A TIP4P model is run with LAMMPS using either these commands
for a cutoff model:
* :doc:`pair_style tip4p/cut <pair_lj_cut_tip4p>`
* :doc:`pair_style lj/cut/tip4p/cut <pair_lj_cut_tip4p>`
or these two commands for a long-range model:
or these commands for a long-range model:
* :doc:`pair_style tip4p/long <pair_coul>`
* :doc:`pair_style lj/cut/tip4p/long <pair_lj_cut_tip4p>`
* :doc:`pair_style lj/long/tip4p/long <pair_lj_long>`
* :doc:`pair_style tip4p/long/soft <pair_fep_soft>`
* :doc:`pair_style lj/cut/tip4p/long/soft <pair_fep_soft>`
* :doc:`kspace_style pppm/tip4p <kspace_style>`
* :doc:`kspace_style pppm/disp/tip4p <kspace_style>`
For both models, the bond lengths and bond angles should be held fixed
using the :doc:`fix shake <fix_shake>` command.
The bond lengths and bond angles should be held fixed using the
:doc:`fix shake <fix_shake>` or :doc:`fix rattle <fix_shake>` command,
unless a parameterization for a flexible TIP4P model is used. The
parameter sets listed below are all for rigid TIP4P model variants and
thus the bond and angle force constants are not used and can be set to
any legal value; only equilibrium length and angle are used.
These are the additional parameters (in real units) to set for O and H
atoms and the water molecule to run a rigid TIP4P model with a cutoff
@ -87,17 +97,18 @@ solver (e.g. Ewald or PPPM in LAMMPS):
| LJ :math:`\epsilon`, :math:`\sigma` of OH, HH = 0.0
|
Note that the when using the TIP4P pair style, the neighbor list
cutoff for Coulomb interactions is effectively extended by a distance
2 \* (OM distance), to account for the offset distance of the
fictitious charges on O atoms in water molecules. Thus it is
typically best in an efficiency sense to use a LJ cutoff >= Coulomb
cutoff + 2\*(OM distance), to shrink the size of the neighbor list.
This leads to slightly larger cost for the long-range calculation, so
you can test the trade-off for your model. The OM distance and the LJ
and Coulombic cutoffs are set in the :doc:`pair_style lj/cut/tip4p/long <pair_lj_cut_tip4p>` command.
Note that the when using the TIP4P pair style, the neighbor list cutoff
for Coulomb interactions is effectively extended by a distance 2 \* (OM
distance), to account for the offset distance of the fictitious charges
on O atoms in water molecules. Thus it is typically best in an
efficiency sense to use a LJ cutoff >= Coulomb cutoff + 2\*(OM
distance), to shrink the size of the neighbor list. This leads to
slightly larger cost for the long-range calculation, so you can test the
trade-off for your model. The OM distance and the LJ and Coulombic
cutoffs are set in the :doc:`pair_style lj/cut/tip4p/long
<pair_lj_cut_tip4p>` command.
Wikipedia also has a nice article on `water models <http://en.wikipedia.org/wiki/Water_model>`_.
Wikipedia also has a nice article on `water models <https://en.wikipedia.org/wiki/Water_model>`_.
----------

7
doc/src/Howto_viz.rst
View File

@ -17,9 +17,10 @@ formats. See the :doc:`Tools <Tools>` page for details.
A Python-based toolkit distributed by our group can read native LAMMPS
dump files, including custom dump files with additional columns of
user-specified atom information, and convert them to various formats
or pipe them into visualization software directly. See the `Pizza.py WWW site <pizza_>`_ for details. Specifically, Pizza.py can convert
LAMMPS dump files into PDB, XYZ, `EnSight <ensight_>`_, and VTK formats.
user-specified atom information, and convert them to various formats or
pipe them into visualization software directly. See the `Pizza.py WWW
site <pizza_>`_ for details. Specifically, Pizza.py can convert LAMMPS
dump files into PDB, XYZ, `EnSight <ensight_>`_, and VTK formats.
Pizza.py can pipe LAMMPS dump files directly into the Raster3d and
RasMol visualization programs. Pizza.py has tools that do interactive
3d OpenGL visualization and one that creates SVG images of dump file

4
doc/src/Install_conda.rst
View File

@ -5,7 +5,7 @@ Binaries are available for MacOS or Linux via `Conda <conda_>`_.
First, one must setup the Conda package manager on your system. Follow the
instructions to install `Miniconda <mini_conda_install_>`_, then create a conda
environment (named `my-lammps-env` or whatever you prefer) for your lammps
environment (named `my-lammps-env` or whatever you prefer) for your LAMMPS
install:
.. code-block:: bash
@ -13,7 +13,7 @@ install:
% conda config --add channels conda-forge
% conda create -n my-lammps-env
Then, you can install lammps on your system with the following command:
Then, you can install LAMMPS on your system with the following command:
.. code-block:: bash

2
doc/src/Install_windows.rst
View File

@ -6,7 +6,7 @@ Windows system can be downloaded from this site:
.. parsed-literal::
`http://packages.lammps.org/windows.html <http://packages.lammps.org/windows.html>`_
`https://packages.lammps.org/windows.html <https://packages.lammps.org/windows.html>`_
Note that each installer package has a date in its name, which
corresponds to the LAMMPS version of the same date. Installers for

4
doc/src/Intro_authors.rst
View File

@ -4,13 +4,13 @@ Authors of LAMMPS
The primary LAMMPS developers are at Sandia National Labs and Temple
University:
* `Steve Plimpton <sjp_>`_, sjplimp at sandia.gov
* `Steve Plimpton <sjp_>`_, sjplimp at gmail.com
* Aidan Thompson, athomps at sandia.gov
* Stan Moore, stamoor at sandia.gov
* Axel Kohlmeyer, akohlmey at gmail.com
* Richard Berger, richard.berger at outlook.com
.. _sjp: http://www.cs.sandia.gov/~sjplimp
.. _sjp: https://sjplimp.github.io
.. _lws: https://www.lammps.org
Past developers include Paul Crozier and Mark Stevens, both at Sandia,

2
doc/src/Intro_citing.rst
View File

@ -27,7 +27,7 @@ namely https://www.lammps.org.
The original publication describing the parallel algorithms used in the
initial versions of LAMMPS is:
`S. Plimpton, Fast Parallel Algorithms for Short-Range Molecular Dynamics, J Comp Phys, 117, 1-19 (1995). <http://www.sandia.gov/~sjplimp/papers/jcompphys95.pdf>`_
`S. Plimpton, Fast Parallel Algorithms for Short-Range Molecular Dynamics, J Comp Phys, 117, 1-19 (1995). <https://doi.org/10.1006/jcph.1995.1039>`_
DOI for the LAMMPS source code

4
doc/src/Intro_features.rst
View File

@ -95,7 +95,7 @@ commands)
* metal-organic framework potentials (QuickFF, MO-FF)
* implicit solvent potentials: hydrodynamic lubrication, Debye
* force-field compatibility with common CHARMM, AMBER, DREIDING, OPLS, GROMACS, COMPASS options
* access to the `OpenKIM Repository <http://openkim.org>`_ of potentials via :doc:`kim command <kim_commands>`
* access to the `OpenKIM Repository <https://openkim.org>`_ of potentials via the :doc:`kim command <kim_commands>`
* hybrid potentials: multiple pair, bond, angle, dihedral, improper potentials can be used in one simulation
* overlaid potentials: superposition of multiple pair potentials (including many-body) with optional scale factor
@ -205,7 +205,7 @@ Pre- and post-processing
.. _pizza: https://lammps.github.io/pizza
.. _python: http://www.python.org
.. _python: https://www.python.org
.. _special:

6
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>` page for details on tools packaged with
LAMMPS. The `Pre/post processing page <http:/www.lammps.org/prepost.html>`_ of the LAMMPS website
LAMMPS. The `Pre/post processing page <https:/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
@ -80,5 +80,5 @@ Here are suggestions on how to perform these tasks:
`Pizza.py <https://lammps.github.io/pizza>`_ which can do certain kinds of
setup, analysis, plotting, and visualization (via OpenGL) for LAMMPS
simulations. It thus provides some functionality for several of the
above bullets. Pizza.py is written in `Python <http://www.python.org>`_
and is available for download from `this page <http://www.cs.sandia.gov/~sjplimp/download.html>`_.
above bullets. Pizza.py is written in `Python <https://www.python.org>`_
and is available for download from `this page <https://sjplimp.github.io/download.html>`_.

4
doc/src/Intro_opensource.rst
View File

@ -23,9 +23,9 @@ applies to LAMMPS is in the LICENSE file included in the LAMMPS distribution.
.. _lgpl: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html
.. _gnuorg: http://www.gnu.org
.. _gnuorg: https://www.gnu.org
.. _opensource: http://www.opensource.org
.. _opensource: https://www.opensource.org
Here is a more specific summary of what the GPL means for LAMMPS users:

BIN
doc/src/JPG/dump.peri.2000.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 200 KiB

BIN
doc/src/JPG/dump.peri.300.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 144 KiB

BIN
doc/src/JPG/dump.peri.600.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 157 KiB

BIN
doc/src/JPG/ovito-peri-snap.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 494 KiB

BIN
doc/src/JPG/pdlammps_fig1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 160 KiB

BIN
doc/src/JPG/pdlammps_fig2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.5 MiB

25
doc/src/Library.rst
View File

@ -2,12 +2,13 @@ LAMMPS Library Interfaces
*************************
As described on the :doc:`library interface to LAMMPS <Howto_library>`
page, LAMMPS can be built as a library (static or shared), so that
it can be called by another code, used in a :doc:`coupled manner
page, LAMMPS can be built as a library (static or shared), so that it
can be called by another code, used in a :doc:`coupled manner
<Howto_couple>` with other codes, or driven through a :doc:`Python
script <Python_head>`. Even the LAMMPS standalone executable is
essentially a thin wrapper on top of the LAMMPS library, creating a
LAMMPS instance, processing input and then existing.
script <Python_head>`. The LAMMPS standalone executable itself is
essentially a thin wrapper on top of the LAMMPS library, which creates a
LAMMPS instance, passes the input for processing to that instance, and
then exits.
Most of the APIs described below are based on C language wrapper
functions in the files ``src/library.h`` and ``src/library.cpp``, but
@ -87,6 +88,18 @@ run LAMMPS in serial mode.
message retrieved <lammps_get_last_error_message>`. We thus
recommend enabling C++ exceptions when using the library interface,
.. admonition:: Using the C library interface as a plugin
:class: note
Rather than including the C library directly and link to the LAMMPS
library at compile time, you can use the ``liblammpsplugin.h`` header
file and the ``liblammpsplugin.c`` C code in the
``examples/COUPLE/plugin`` folder for an interface to LAMMPS that is
largely identical to the regular library interface, only that it will
load a LAMMPS shared library file at runtime. This can be useful for
applications where the interface to LAMMPS would be an optional
feature.
.. warning::
No checks are made on the arguments of the function calls of the C
@ -163,5 +176,3 @@ The following links provide some examples and references to the C++ API.
:maxdepth: 1
Cplusplus

6
doc/src/Library_create.rst
View File

@ -11,6 +11,7 @@ This section documents the following functions:
- :cpp:func:`lammps_mpi_finalize`
- :cpp:func:`lammps_kokkos_finalize`
- :cpp:func:`lammps_python_finalize`
- :cpp:func:`lammps_error`
--------------------
@ -115,3 +116,8 @@ calling program.
.. doxygenfunction:: lammps_python_finalize
:project: progguide
-----------------------
.. doxygenfunction:: lammps_error
:project: progguide

8
doc/src/Library_objects.rst
View File

@ -6,6 +6,7 @@ fixes, or variables in LAMMPS using the following functions:
- :cpp:func:`lammps_extract_compute`
- :cpp:func:`lammps_extract_fix`
- :cpp:func:`lammps_extract_variable_datatype`
- :cpp:func:`lammps_extract_variable`
- :cpp:func:`lammps_set_variable`
@ -21,6 +22,11 @@ fixes, or variables in LAMMPS using the following functions:
-----------------------
.. doxygenfunction:: lammps_extract_variable_datatype
:project: progguide
-----------------------
.. doxygenfunction:: lammps_extract_variable
:project: progguide
@ -36,3 +42,5 @@ fixes, or variables in LAMMPS using the following functions:
.. doxygenenum:: _LMP_STYLE_CONST
.. doxygenenum:: _LMP_TYPE_CONST
.. doxygenenum:: _LMP_VAR_CONST

30
doc/src/Library_properties.rst
View File

@ -15,21 +15,21 @@ This section documents the following functions:
--------------------
The library interface allows extraction of different kinds of
information about the active simulation instance and also
modifications to it. This enables combining of a LAMMPS simulation
with other processing and simulation methods computed by the calling
code, or by another code that is coupled to LAMMPS via the library
interface. In some cases the data returned is direct reference to the
original data inside LAMMPS, cast to a void pointer. In that case the
data needs to be cast to a suitable pointer for the calling program to
access it, and you may need to know the correct dimensions and
lengths. This also means you can directly change those value(s) from
the calling program, e.g. to modify atom positions. Of course, this
should be done with care. When accessing per-atom data, please note
that this data is the per-processor **local** data and is indexed
accordingly. Per-atom data can change sizes and ordering at every
neighbor list rebuild or atom sort event as atoms migrate between
The library interface allows the extraction of different kinds of
information about the active simulation instance and also---in some
cases---to apply modifications to it. This enables combining of a
LAMMPS simulation with other processing and simulation methods computed
by the calling code, or by another code that is coupled to LAMMPS via
the library interface. In some cases the data returned is direct
reference to the original data inside LAMMPS, cast to a void pointer.
In that case the data needs to be cast to a suitable pointer for the
calling program to access it, and you may need to know the correct
dimensions and lengths. This also means you can directly change those
value(s) from the calling program (e.g., to modify atom positions). Of
course, changing values should be done with care. When accessing per-atom
data, please note that these data are the per-processor **local** data and are
indexed accordingly. Per-atom data can change sizes and ordering at
every neighbor list rebuild or atom sort event as atoms migrate between
sub-domains and processors.
.. code-block:: C

7
doc/src/Library_utility.rst
View File

@ -19,6 +19,7 @@ functions. They do not directly call the LAMMPS library.
- :cpp:func:`lammps_force_timeout`
- :cpp:func:`lammps_has_error`
- :cpp:func:`lammps_get_last_error_message`
- :cpp:func:`lammps_python_api_version`
The :cpp:func:`lammps_free` function is a clean-up function to free
memory that the library had allocated previously via other function
@ -100,3 +101,9 @@ where such memory buffers were allocated that require the use of
.. doxygenfunction:: lammps_get_last_error_message
:project: progguide
-----------------------
.. doxygenfunction:: lammps_python_api_version
:project: progguide

2
doc/src/Manual.rst
View File

@ -42,7 +42,7 @@ descriptions of all commands included in the LAMMPS code.
.. only:: html
Once you are familiar with LAMMPS, you may want to bookmark
:doc:`this page <Commands_all>` since it gives quick access
:doc:`this page <Commands_all>` since it gives quick access to
the documentation for all LAMMPS commands.
.. _lws: https://www.lammps.org

6
doc/src/Modify_style.rst
View File

@ -359,6 +359,12 @@ you are uncertain, please ask.
- I/O is done via the C-style stdio library and **not** iostreams.
- Do not use so-called "alternative tokens" like ``and``, ``or``,
``not`` and similar, but rather use the corresponding operators
``&&``, ``||``, and ``!``. The alternative tokens are not available
by default on all compilers, and also we want to maintain a consistent
programming style.
- Output to the screen and the logfile should be using the corresponding
FILE pointers and only be done on MPI rank 0. Use the :cpp:func:`utils::logmesg`
convenience function where possible.

42
doc/src/Packages_details.rst
View File

@ -135,6 +135,8 @@ commands to write and read data using the ADIOS library.
**Authors:** Norbert Podhorszki (ORNL) from the ADIOS developer team.
.. versionadded:: 28Feb2019
**Install:**
This package has :ref:`specific installation instructions <adios>` on the :doc:`Build extras <Build_extras>` page.
@ -199,6 +201,7 @@ particle models including ellipsoids, 2d lines, and 3d triangles.
* :doc:`Howto spherical <Howto_spherical>`
* :doc:`pair_style gayberne <pair_gayberne>`
* :doc:`pair_style resquared <pair_resquared>`
* :doc:`pair_style ylz <pair_ylz>`
* `doc/PDF/pair_gayberne_extra.pdf <PDF/pair_gayberne_extra.pdf>`_
* `doc/PDF/pair_resquared_extra.pdf <PDF/pair_resquared_extra.pdf>`_
* examples/ASPHERE
@ -365,6 +368,8 @@ and also support self-propelled particles.
**Authors:** Sam Cameron (University of Bristol),
Stefan Paquay (while at Brandeis University) (initial version of fix propel/self)
.. versionadded:: 14May2021
Example inputs are in the examples/PACKAGES/brownian folder.
----------
@ -593,6 +598,8 @@ To use this package, also the :ref:`KSPACE <PKG-KSPACE>` and
**Author:** Trung Nguyen and Monica Olvera de la Cruz (Northwestern U)
.. versionadded:: 2Jul2021
**Supporting info:**
* src/DIELECTRIC: filenames -> commands
@ -1072,7 +1079,7 @@ H5MD is a format for molecular simulations, built on top of HDF5.
This package implements a :doc:`dump h5md <dump_h5md>` command to output
LAMMPS snapshots in this format.
.. _HDF5: http://www.hdfgroup.org/HDF5
.. _HDF5: https://www.hdfgroup.org/solutions/hdf5
To use this package you must have the HDF5 library available on your
system.
@ -1513,6 +1520,8 @@ workflows via the `MolSSI Driver Interface
**Author:** Taylor Barnes - MolSSI, taylor.a.barnes at gmail.com
.. versionadded:: 14May2021
**Install:**
This package has :ref:`specific installation instructions <mdi>` on
@ -1597,6 +1606,8 @@ of Alabama), Leonid V. Zhigilei (University of Virginia)
**Author of the *mesocnt* styles:**
Philipp Kloza (U Cambridge)
.. versionadded:: 15Jun2020
**Supporting info:**
* src/MESONT: filenames -> commands
@ -1689,6 +1700,8 @@ compiled on your system.
**Author:** Andreas Singraber
.. versionadded:: 27May2021
**Install:**
This package has :ref:`specific installation instructions <ml-hdnnp>` on the
@ -1723,6 +1736,8 @@ must be installed.
**Author:** Aidan Thompson (Sandia), Nicholas Lubbers (LANL).
.. versionadded:: 30Jun2020
**Supporting info:**
* src/ML-IAP: filenames -> commands
@ -1767,6 +1782,8 @@ Aidan Thompson^3, Gabor Csanyi^2, Christoph Ortner^4, Ralf Drautz^1.
^4: University of British Columbia, Vancouver, BC, Canada
.. versionadded:: 14May2021
**Install:**
This package has :ref:`specific installation instructions <ml-pace>` on the
@ -1868,6 +1885,8 @@ of a neural network.
This package was written by Christopher Barrett
with contributions by Doyl Dickel, Mississippi State University.
.. versionadded:: 27May2021
**Supporting info:**
* src/ML-RANN: filenames -> commands
@ -1993,7 +2012,7 @@ support for new file formats can be added to LAMMPS (or VMD or other
programs that use them) without having to re-compile the application
itself. More information about the VMD molfile plugins can be found
at
`http://www.ks.uiuc.edu/Research/vmd/plugins/molfile <http://www.ks.uiuc.edu/Research/vmd/plugins/molfile>`_.
`https://www.ks.uiuc.edu/Research/vmd/plugins/molfile <https://www.ks.uiuc.edu/Research/vmd/plugins/molfile>`_.
**Author:** Axel Kohlmeyer (Temple U).
@ -2084,7 +2103,7 @@ NETCDF package
Dump styles for writing NetCDF formatted dump files. NetCDF is a
portable, binary, self-describing file format developed on top of
HDF5. The file contents follow the AMBER NetCDF trajectory conventions
(http://ambermd.org/netcdf/nctraj.xhtml), but include extensions.
(https://ambermd.org/netcdf/nctraj.xhtml), but include extensions.
To use this package you must have the NetCDF library available on your
system.
@ -2095,7 +2114,7 @@ tools:
* `Ovito <ovito_>`_ (Ovito supports the AMBER convention and the extensions mentioned above)
* `VMD <vmd-home_>`_
.. _ovito: http://www.ovito.org
.. _ovito: https://www.ovito.org
.. _vmd-home: https://www.ks.uiuc.edu/Research/vmd/
@ -2239,6 +2258,7 @@ Foster (UTSA).
**Supporting info:**
* src/PERI: filenames -> commands
* :doc:`Peridynamics Howto <Howto_peri>`
* `doc/PDF/PDLammps_overview.pdf <PDF/PDLammps_overview.pdf>`_
* `doc/PDF/PDLammps_EPS.pdf <PDF/PDLammps_EPS.pdf>`_
* `doc/PDF/PDLammps_VES.pdf <PDF/PDLammps_VES.pdf>`_
@ -2303,6 +2323,8 @@ try to load the contained plugins automatically at start-up.
**Authors:** Axel Kohlmeyer (Temple U)
.. versionadded:: 8Apr2021
**Supporting info:**
* src/PLUGIN: filenames -> commands
@ -2456,7 +2478,7 @@ A :doc:`fix qmmm <fix_qmmm>` command which allows LAMMPS to be used as
the MM code in a QM/MM simulation. This is currently only available
in combination with the `Quantum ESPRESSO <espresso_>`_ package.
.. _espresso: http://www.quantum-espresso.org
.. _espresso: https://www.quantum-espresso.org
To use this package you must have Quantum ESPRESSO (QE) available on
your system and include its coupling library in the compilation and
@ -2868,7 +2890,7 @@ collection of atoms by wrapping the `Voro++ library <voro-home_>`_. This
can be used to calculate the local volume or each atoms or its near
neighbors.
.. _voro-home: http://math.lbl.gov/voro++
.. _voro-home: https://math.lbl.gov/voro++
To use this package you must have the Voro++ library available on your
system.
@ -2902,9 +2924,9 @@ A :doc:`dump vtk <dump_vtk>` command which outputs snapshot info in the
`VTK format <vtk_>`_, enabling visualization by `Paraview <paraview_>`_ or
other visualization packages.
.. _vtk: http://www.vtk.org
.. _vtk: https://www.vtk.org
.. _paraview: http://www.paraview.org
.. _paraview: https://www.paraview.org
To use this package you must have VTK library available on your
system.
@ -2941,11 +2963,13 @@ which discuss the `QuickFF <quickff_>`_ methodology.
.. _vanduyfhuys2015: https://doi.org/10.1002/jcc.23877
.. _vanduyfhuys2018: https://doi.org/10.1002/jcc.25173
.. _quickff: http://molmod.github.io/QuickFF
.. _quickff: https://molmod.github.io/QuickFF
.. _yaff: https://github.com/molmod/yaff
**Author:** Steven Vandenbrande.
.. versionadded:: 1Feb2019
**Supporting info:**
* src/YAFF/README

20
doc/src/Python_examples.rst
View File

@ -43,26 +43,18 @@ Note that for AtomEye, you need version 3, and there is a line in the
scripts that specifies the path and name of the executable. See the
AtomEye web pages for more details:
* `http://li.mit.edu/Archive/Graphics/A/ <atomeye_>`_
* `http://li.mit.edu/Archive/Graphics/A3/A3.html <atomeye3_>`_
* `http://li.mit.edu/Archive/Graphics/A/ <http://li.mit.edu/Archive/Graphics/A/>`_
* `http://li.mit.edu/Archive/Graphics/A3/A3.html <http://li.mit.edu/Archive/Graphics/A3/A3.html>`_
.. _atomeye: http://li.mit.edu/Archive/Graphics/A/
.. _atomeye3: http://li.mit.edu/Archive/Graphics/A3/A3.html
The latter link is to AtomEye 3 which has the scripting
capability needed by these Python scripts.
The latter link is to AtomEye 3 which has the scripting capability
needed by these Python scripts.
Note that for PyMol, you need to have built and installed the
open-source version of PyMol in your Python, so that you can import it
from a Python script. See the PyMol web pages for more details:
* `https://www.pymol.org <pymolhome_>`_
* `https://github.com/schrodinger/pymol-open-source <pymolopen_>`_
.. _pymolhome: https://www.pymol.org
.. _pymolopen: https://github.com/schrodinger/pymol-open-source
* `https://www.pymol.org <https://www.pymol.org>`_
* `https://github.com/schrodinger/pymol-open-source <https://github.com/schrodinger/pymol-open-source>`_
The latter link is to the open-source version.

10
doc/src/Python_head.rst
View File

@ -18,17 +18,17 @@ together.
Python_error
Python_trouble
If you are not familiar with `Python <http://www.python.org>`_, it is a
If you are not familiar with `Python <https://www.python.org>`_, it is a
powerful scripting and programming language which can do almost
everything that compiled languages like C, C++, or Fortran can do in
fewer lines of code. It also comes with a large collection of add-on
modules for many purposes (either bundled or easily installed from
Python code repositories). The major drawback is slower execution speed
of the script code compared to compiled programming languages. But when
the script code is interfaced to optimized compiled code, performance can
be on par with a standalone executable, for as long as the scripting is
restricted to high-level operations. Thus Python is also convenient to
use as a "glue" language to "drive" a program through its library
the script code is interfaced to optimized compiled code, performance
can be on par with a standalone executable, for as long as the scripting
is restricted to high-level operations. Thus Python is also convenient
to use as a "glue" language to "drive" a program through its library
interface, or to hook multiple pieces of software together, such as a
simulation code and a visualization tool, or to run a coupled
multi-scale or multi-physics model.

34
doc/src/Python_neighbor.rst
View File

@ -38,6 +38,40 @@ using the NumPy access method.
for n in np.nditer(nlist):
print(" atom {} with ID {}".format(n,tags[n]))
Another example for extracting a full neighbor list without evaluating a
potential is shown below.
.. code-block:: python
from lammps import lammps
import numpy as np
lmp = lammps()
lmp.commands_string("""
newton off
region box block -2 2 -2 2 -2 2
lattice fcc 1.0
create_box 1 box
create_atoms 1 box
mass 1 1.0
pair_style zero 1.0 full
pair_coeff * *
run 0 post no""")
# look up the neighbor list
nlidx = lmp.find_pair_neighlist('zero')
nl = lmp.numpy.get_neighlist(nlidx)
tags = lmp.extract_atom('id')
print("full neighbor list with {} entries".format(nl.size))
# print neighbor list contents
for i in range(0,nl.size):
idx, nlist = nl.get(i)
print("\natom {} with ID {} has {} neighbors:".format(idx,tags[idx],nlist.size))
if nlist.size > 0:
for n in np.nditer(nlist):
pass
print(" atom {} with ID {}".format(n,tags[n]))
**Methods:**
* :py:meth:`lammps.get_neighlist() <lammps.lammps.get_neighlist()>`: Get neighbor list for given index

9
doc/src/Run_basics.rst
View File

@ -30,12 +30,13 @@ executable itself can be placed elsewhere.
.. note::
The redirection operator "<" will not always work when running
in parallel with mpirun or mpiexec; for those systems the -in form is required.
The redirection operator "<" will not always work when running in
parallel with ``mpirun`` or ``mpiexec``; for those systems the -in
form is required.
As LAMMPS runs it prints info to the screen and a logfile named
*log.lammps*\ . More info about output is given on the
:doc:`screen and logfile output <Run_output>` page.
*log.lammps*\ . More info about output is given on the :doc:`screen and
logfile output <Run_output>` page.
If LAMMPS encounters errors in the input script or while running a
simulation it will print an ERROR message and stop or a WARNING

20
doc/src/Run_options.rst
View File

@ -93,13 +93,13 @@ switch is not set (the default), LAMMPS will operate as if the KOKKOS
package were not installed; i.e. you can run standard LAMMPS or with
the GPU or OPENMP packages, for testing or benchmarking purposes.
Additional optional keyword/value pairs can be specified which
determine how Kokkos will use the underlying hardware on your
platform. These settings apply to each MPI task you launch via the
"mpirun" or "mpiexec" command. You may choose to run one or more MPI
tasks per physical node. Note that if you are running on a desktop
machine, you typically have one physical node. On a cluster or
supercomputer there may be dozens or 1000s of physical nodes.
Additional optional keyword/value pairs can be specified which determine
how Kokkos will use the underlying hardware on your platform. These
settings apply to each MPI task you launch via the ``mpirun`` or
``mpiexec`` command. You may choose to run one or more MPI tasks per
physical node. Note that if you are running on a desktop machine, you
typically have one physical node. On a cluster or supercomputer there
may be dozens or 1000s of physical nodes.
Either the full word or an abbreviation can be used for the keywords.
Note that the keywords do not use a leading minus sign. I.e. the
@ -148,9 +148,9 @@ one of these 4 environment variables
MV2_COMM_WORLD_LOCAL_RANK (Mvapich)
OMPI_COMM_WORLD_LOCAL_RANK (OpenMPI)
which are initialized by the "srun", "mpirun" or "mpiexec" commands.
The environment variable setting for each MPI rank is used to assign a
unique GPU ID to the MPI task.
which are initialized by the ``srun``, ``mpirun``, or ``mpiexec``
commands. The environment variable setting for each MPI rank is used to
assign a unique GPU ID to the MPI task.
.. parsed-literal::

59
doc/src/Run_output.rst
View File

@ -16,46 +16,47 @@ simulation. An example set of statistics is shown here:
.. parsed-literal::
Loop time of 2.81192 on 4 procs for 300 steps with 2004 atoms
Loop time of 0.942801 on 4 procs for 300 steps with 2004 atoms
Performance: 18.436 ns/day 1.302 hours/ns 106.689 timesteps/s
97.0% CPU use with 4 MPI tasks x no OpenMP threads
Performance: 54.985 ns/day, 0.436 hours/ns, 318.201 timesteps/s, 637.674 katom-step/s
195.2% CPU use with 2 MPI tasks x 2 OpenMP threads
MPI task timings breakdown:
MPI task timing breakdown:
Section \| min time \| avg time \| max time \|%varavg\| %total
---------------------------------------------------------------
Pair \| 1.9808 \| 2.0134 \| 2.0318 \| 1.4 \| 71.60
Bond \| 0.0021894 \| 0.0060319 \| 0.010058 \| 4.7 \| 0.21
Kspace \| 0.3207 \| 0.3366 \| 0.36616 \| 3.1 \| 11.97
Neigh \| 0.28411 \| 0.28464 \| 0.28516 \| 0.1 \| 10.12
Comm \| 0.075732 \| 0.077018 \| 0.07883 \| 0.4 \| 2.74
Output \| 0.00030518 \| 0.00042665 \| 0.00078821 \| 1.0 \| 0.02
Modify \| 0.086606 \| 0.086631 \| 0.086668 \| 0.0 \| 3.08
Other \| \| 0.007178 \| \| \| 0.26
Pair \| 0.61419 \| 0.62872 \| 0.64325 \| 1.8 \| 66.69
Bond \| 0.0028608 \| 0.0028899 \| 0.002919 \| 0.1 \| 0.31
Kspace \| 0.12652 \| 0.14048 \| 0.15444 \| 3.7 \| 14.90
Neigh \| 0.10242 \| 0.10242 \| 0.10242 \| 0.0 \| 10.86
Comm \| 0.026753 \| 0.027593 \| 0.028434 \| 0.5 \| 2.93
Output \| 0.00018341 \| 0.00030942 \| 0.00043542 \| 0.0 \| 0.03
Modify \| 0.039117 \| 0.039348 \| 0.039579 \| 0.1 \| 4.17
Other \| \| 0.001041 \| \| \| 0.11
Nlocal: 501 ave 508 max 490 min
Histogram: 1 0 0 0 0 0 1 1 0 1
Nghost: 6586.25 ave 6628 max 6548 min
Histogram: 1 0 1 0 0 0 1 0 0 1
Neighs: 177007 ave 180562 max 170212 min
Histogram: 1 0 0 0 0 0 0 1 1 1
Nlocal: 1002 ave 1006 max 998 min
Histogram: 1 0 0 0 0 0 0 0 0 1
Nghost: 8670.5 ave 8691 max 8650 min
Histogram: 1 0 0 0 0 0 0 0 0 1
Neighs: 354010 ave 357257 max 350763 min
Histogram: 1 0 0 0 0 0 0 0 0 1
Total # of neighbors = 708028
Ave neighs/atom = 353.307
Ave special neighs/atom = 2.34032
Total # of neighbors = 708020
Ave neighs/atom = 353.30339
Ave special neighs/atom = 2.3403194
Neighbor list builds = 26
Dangerous builds = 0
----------
The first section provides a global loop timing summary. The *loop
time* is the total wall-clock time for the simulation to run. The
*Performance* line is provided for convenience to help predict how
long it will take to run a desired physical simulation. The *CPU use*
line provides the CPU utilization per MPI task; it should be close to
100% times the number of OpenMP threads (or 1 of not using OpenMP).
Lower numbers correspond to delays due to file I/O or insufficient
thread utilization.
The first section provides a global loop timing summary. The *loop time*
is the total wall-clock time for the simulation to run. The
*Performance* line is provided for convenience to help predict how long
it will take to run a desired physical simulation and to have numbers
useful for performance comparison between different simulation settings
or system sizes. The *CPU use* line provides the CPU utilization per
MPI task; it should be close to 100% times the number of OpenMP threads
(or 1 of not using OpenMP). Lower numbers correspond to delays due to
file I/O or insufficient thread utilization.
----------

4
doc/src/Run_windows.rst
View File

@ -25,8 +25,8 @@ in parallel, follow these steps.
Download and install a compatible MPI library binary package:
* for 32-bit Windows: `mpich2-1.4.1p1-win-ia32.msi <http://download.lammps.org/thirdparty/mpich2-1.4.1p1-win-ia32.msi>`_
* for 64-bit Windows: `mpich2-1.4.1p1-win-x86-64.msi <http://download.lammps.org/thirdparty/mpich2-1.4.1p1-win-x86-64.msi>`_
* for 32-bit Windows: `mpich2-1.4.1p1-win-ia32.msi <https://download.lammps.org/thirdparty/mpich2-1.4.1p1-win-ia32.msi>`_
* for 64-bit Windows: `mpich2-1.4.1p1-win-x86-64.msi <https://download.lammps.org/thirdparty/mpich2-1.4.1p1-win-x86-64.msi>`_
The LAMMPS Windows installer packages will automatically adjust your
path for the default location of this MPI package. After the

15
doc/src/Speed_gpu.rst
View File

@ -39,7 +39,7 @@ toolkit software on your system (this is only tested on Linux
and unsupported on Windows):
* Check if you have an NVIDIA GPU: cat /proc/driver/nvidia/gpus/\*/information
* Go to http://www.nvidia.com/object/cuda_get.html
* Go to https://developer.nvidia.com/cuda-downloads
* Install a driver and toolkit appropriate for your system (SDK is not necessary)
* Run lammps/lib/gpu/nvc_get_devices (after building the GPU library, see below) to
list supported devices and properties
@ -76,10 +76,11 @@ instructions.
**Run with the GPU package from the command line:**
The mpirun or mpiexec command sets the total number of MPI tasks used
by LAMMPS (one or multiple per compute node) and the number of MPI
tasks used per node. E.g. the mpirun command in MPICH does this via
its -np and -ppn switches. Ditto for OpenMPI via -np and -npernode.
The ``mpirun`` or ``mpiexec`` command sets the total number of MPI tasks
used by LAMMPS (one or multiple per compute node) and the number of MPI
tasks used per node. E.g. the ``mpirun`` command in MPICH does this via
its ``-np`` and ``-ppn`` switches. Ditto for OpenMPI via ``-np`` and
``-npernode``.
When using the GPU package, you cannot assign more than one GPU to a
single MPI task. However multiple MPI tasks can share the same GPU,
@ -129,8 +130,8 @@ GPU package pair styles.
**Or run with the GPU package by editing an input script:**
The discussion above for the mpirun/mpiexec command, MPI tasks/node,
and use of multiple MPI tasks/GPU is the same.
The discussion above for the ``mpirun`` or ``mpiexec`` command, MPI
tasks/node, and use of multiple MPI tasks/GPU is the same.
Use the :doc:`suffix gpu <suffix>` command, or you can explicitly add an
"gpu" suffix to individual styles in your input script, e.g.

2
doc/src/Speed_intel.rst
View File

@ -537,5 +537,5 @@ References
""""""""""
* Brown, W.M., Carrillo, J.-M.Y., Mishra, B., Gavhane, N., Thakkar, F.M., De Kraker, A.R., Yamada, M., Ang, J.A., Plimpton, S.J., "Optimizing Classical Molecular Dynamics in LAMMPS", in Intel Xeon Phi Processor High Performance Programming: Knights Landing Edition, J. Jeffers, J. Reinders, A. Sodani, Eds. Morgan Kaufmann.
* Brown, W. M., Semin, A., Hebenstreit, M., Khvostov, S., Raman, K., Plimpton, S.J. `Increasing Molecular Dynamics Simulation Rates with an 8-Fold Increase in Electrical Power Efficiency. <http://dl.acm.org/citation.cfm?id=3014915>`_ 2016 High Performance Computing, Networking, Storage and Analysis, SC16: International Conference (pp. 82-95).
* Brown, W. M., Semin, A., Hebenstreit, M., Khvostov, S., Raman, K., Plimpton, S.J. `Increasing Molecular Dynamics Simulation Rates with an 8-Fold Increase in Electrical Power Efficiency. <https://dl.acm.org/citation.cfm?id=3014915>`_ 2016 High Performance Computing, Networking, Storage and Analysis, SC16: International Conference (pp. 82-95).
* Brown, W.M., Carrillo, J.-M.Y., Gavhane, N., Thakkar, F.M., Plimpton, S.J. Optimizing Legacy Molecular Dynamics Software with Directive-Based Offload. Computer Physics Communications. 2015. 195: p. 95-101.

17
doc/src/Speed_kokkos.rst
View File

@ -72,12 +72,12 @@ See the :ref:`Build extras <kokkos>` page for instructions.
Running LAMMPS with the KOKKOS package
""""""""""""""""""""""""""""""""""""""
All Kokkos operations occur within the context of an individual MPI
task running on a single node of the machine. The total number of MPI
tasks used by LAMMPS (one or multiple per compute node) is set in the
usual manner via the mpirun or mpiexec commands, and is independent of
Kokkos. E.g. the mpirun command in OpenMPI does this via its -np and
-npernode switches. Ditto for MPICH via -np and -ppn.
All Kokkos operations occur within the context of an individual MPI task
running on a single node of the machine. The total number of MPI tasks
used by LAMMPS (one or multiple per compute node) is set in the usual
manner via the ``mpirun`` or ``mpiexec`` commands, and is independent of
Kokkos. E.g. the mpirun command in OpenMPI does this via its ``-np`` and
``-npernode`` switches. Ditto for MPICH via ``-np`` and ``-ppn``.
Running on a multi-core CPU
^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -168,7 +168,7 @@ for your MPI installation), binding can be forced with these flags:
.. parsed-literal::
OpenMPI 1.8: mpirun -np 2 --bind-to socket --map-by socket ./lmp_openmpi ...
OpenMPI 1.8: mpirun -np 2 --bind-to socket --map-by socket ./lmp_openmpi ...
Mvapich2 2.0: mpiexec -np 2 --bind-to socket --map-by socket ./lmp_mvapich ...
For binding threads with KOKKOS OpenMP, use thread affinity environment
@ -310,7 +310,8 @@ Alternatively the effect of the "-sf" or "-pk" switches can be
duplicated by adding the :doc:`package kokkos <package>` or :doc:`suffix kk <suffix>` commands to your input script.
The discussion above for building LAMMPS with the KOKKOS package, the
mpirun/mpiexec command, and setting appropriate thread are the same.
``mpirun`` or ``mpiexec`` command, and setting appropriate thread
properties are the same.
You must still use the "-k on" :doc:`command-line switch <Run_options>`
to enable the KOKKOS package, and specify its additional arguments for

10
doc/src/Speed_omp.rst
View File

@ -33,8 +33,8 @@ These examples assume one or more 16-core nodes.
mpirun -np 4 lmp_omp -sf omp -pk omp 4 -in in.script # 4 MPI tasks, 4 threads/task
mpirun -np 32 -ppn 4 lmp_omp -sf omp -pk omp 4 -in in.script # 8 nodes, 4 MPI tasks/node, 4 threads/task
The mpirun or mpiexec command sets the total number of MPI tasks used
by LAMMPS (one or multiple per compute node) and the number of MPI
The ``mpirun`` or ``mpiexec`` command sets the total number of MPI tasks
used by LAMMPS (one or multiple per compute node) and the number of MPI
tasks used per node. E.g. the mpirun command in MPICH does this via
its -np and -ppn switches. Ditto for OpenMPI via -np and -npernode.
@ -58,8 +58,8 @@ OMP_NUM_THREADS environment variable.
Or run with the OPENMP package by editing an input script
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
The discussion above for the mpirun/mpiexec command, MPI tasks/node,
and threads/MPI task is the same.
The discussion above for the ``mpirun`` or ``mpiexec`` command, MPI
tasks/node, and threads/MPI task is the same.
Use the :doc:`suffix omp <suffix>` command, or you can explicitly add an
"omp" suffix to individual styles in your input script, e.g.
@ -97,7 +97,7 @@ sub-section.
A description of the multi-threading strategy used in the OPENMP
package and some performance examples are
`presented here <http://sites.google.com/site/akohlmey/software/lammps-icms/lammps-icms-tms2011-talk.pdf?attredirects=0&d=1>`_.
`presented here <https://drive.google.com/file/d/1d1gLK6Ru6aPYB50Ld2tO10Li8zgPVNB8/view?usp=sharing>`_.
Guidelines for best performance
"""""""""""""""""""""""""""""""

24
doc/src/Speed_packages.rst
View File

@ -117,33 +117,15 @@ script.
with all its accelerator packages installed. Note however that the
INTEL and KOKKOS packages require you to choose one of their
hardware options when building for a specific platform. I.e. CPU or
Phi option for the INTEL package. Or the OpenMP, Cuda, or Phi
option for the KOKKOS package.
Phi option for the INTEL package. Or the OpenMP, CUDA, HIP, SYCL,
or Phi option for the KOKKOS package. Or the OpenCL, HIP, or CUDA
option for the GPU package.
These are the exceptions. You cannot build a single executable with:
* both the INTEL Phi and KOKKOS Phi options
* the INTEL Phi or Kokkos Phi option, and the GPU package
See the examples/accelerate/README and make.list files for sample
Make.py commands that build LAMMPS with any or all of the accelerator
packages. As an example, here is a command that builds with all the
GPU related packages installed (GPU, KOKKOS with Cuda), including
settings to build the needed auxiliary GPU libraries for Kepler GPUs:
.. code-block:: bash
Make.py -j 16 -p omp gpu kokkos -cc nvcc wrap=mpi -gpu mode=double arch=35 -kokkos cuda arch=35 lib-all file mpi
The examples/accelerate directory also has input scripts that can be
used with all of the accelerator packages. See its README file for
details.
Likewise, the bench directory has FERMI and KEPLER and PHI
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://www.lammps.org/bench.html>`_ of the LAMMPS website gives
performance results for the various accelerator packages for several
of the standard LAMMPS benchmark problems, as a function of problem

13
doc/src/Tools.rst
View File

@ -205,6 +205,7 @@ scripts are available:
whitespace.py # detects TAB characters and trailing whitespace
homepage.py # detects outdated LAMMPS homepage URLs (pointing to sandia.gov instead of lammps.org)
errordocs.py # detects deprecated error docs in header files
versiontags.py # detects .. versionadded:: or .. versionchanged:: with pending version date
The tools need to be given the main folder of the LAMMPS distribution
or individual file names as argument and will by default check them
@ -397,7 +398,7 @@ ipp tool
------------------
The tools/ipp directory contains a Perl script ipp which can be used
to facilitate the creation of a complicated file (say, a lammps input
to facilitate the creation of a complicated file (say, a LAMMPS input
script or tools/createatoms input file) using a template file.
ipp was created and is maintained by Reese Jones (Sandia), rjones at
@ -512,8 +513,8 @@ with an ``.inputrc`` file in the home directory. For application
specific customization, the LAMMPS shell uses the name "lammps-shell".
For more information about using and customizing an application using
readline, please see the available documentation at:
`http://www.gnu.org/s/readline/#Documentation
<http://www.gnu.org/s/readline/#Documentation>`_
https://www.gnu.org/software/readline/
Additional commands
^^^^^^^^^^^^^^^^^^^
@ -715,7 +716,7 @@ See the README.pdf file for more information.
These scripts were written by Arun Subramaniyan at Purdue Univ
(asubrama at purdue.edu).
.. _matlabhome: http://www.mathworks.com
.. _matlabhome: https://www.mathworks.com
----------
@ -1046,7 +1047,7 @@ the binary file. This usually is a so-called little endian hardware
SWIG interface
--------------
The `SWIG tool <http://swig.org>`_ offers a mostly automated way to
The `SWIG tool <https://swig.org>`_ offers a mostly automated way to
incorporate compiled code modules into scripting languages. It
processes the function prototypes in C and generates wrappers for a wide
variety of scripting languages from it. Thus it can also be applied to
@ -1126,7 +1127,7 @@ data passed or returned as pointers are included in the ``lammps.i``
file. So most of the functionality of the library interface should be
accessible. What works and what does not depends a bit on the
individual language for which the wrappers are built and how well SWIG
supports those. The `SWIG documentation <http://swig.org/doc.html>`_
supports those. The `SWIG documentation <https://swig.org/doc.html>`_
has very detailed instructions and recommendations.
Usage examples

27
doc/src/atom_style.rst
View File

@ -91,7 +91,7 @@ quantities.
+--------------+-----------------------------------------------------+--------------------------------------+
| *charge* | charge | atomic system with charges |
+--------------+-----------------------------------------------------+--------------------------------------+
| *dielectric* | dipole, area, curvature | system with surface polarization |
| *dielectric* | normx normy normz area/patch ed em epsilon curv | system with surface polarization |
+--------------+-----------------------------------------------------+--------------------------------------+
| *dipole* | charge and dipole moment | system with dipolar particles |
+--------------+-----------------------------------------------------+--------------------------------------+
@ -180,16 +180,21 @@ vector with the 3 diameters of the ellipsoid and a quaternion 4-vector
with its orientation.
For the *dielectric* style, each particle can be either a physical
particle (e.g. an ion), or an interface particle representing a
boundary element. For physical particles, the per-particle properties
are the same as atom_style full. For interface particles, in addition
to these properties, each particle also has an area, a normal unit
vector, a mean local curvature, the mean and difference of the
dielectric constants of two sides of the interface, and the local
dielectric constant at the boundary element. The distinction between
the physical and interface particles is only meaningful when :doc:`fix
polarize <fix_polarize>` commands are applied to the interface
particles.
particle (e.g. an ion), or an interface particle representing a boundary
element between two regions of different dielectric constant. For
interface particles, in addition to the properties associated with
atom_style full, each particle also should be assigned a normal unit
vector (defined by normx, normy, normz), an area (area/patch), the
difference and mean of the dielectric constants of two sides of the
interface along the direction of the normal vector (ed and em), the
local dielectric constant at the boundary element (epsilon), and a mean
local curvature (curv). Physical particles must be assigned these
values, as well, but only their local dielectric constants will be used;
see documentation for associated :doc:`pair styles <pair_dielectric>`
and :doc:`fixes <fix_polarize>`. The distinction between the physical
and interface particles is only meaningful when :doc:`fix polarize
<fix_polarize>` commands are applied to the interface particles. This
style is part of the DIELECTRIC package.
For the *dipole* style, a point dipole is defined for each point
particle. Note that if you wish the particles to be finite-size

58
doc/src/bond_bpm_rotational.rst
View File

@ -138,15 +138,14 @@ the *overlay/pair* keyword. These settings require specific
restrictions. Further details can be found in the `:doc: how to
<Howto_BPM>` page on BPMs.
If the *store/local* keyword is used, this fix will track bonds that
If the *store/local* keyword is used, an internal fix will track bonds that
break during the simulation. Whenever a bond breaks, data is processed
and transferred to an internal fix labeled *fix_ID*. This allows the
local data to be accessed by other LAMMPS commands.
Following any optional keyword/value arguments, a list of one or more
attributes is specified. These include the IDs of the two atoms in
the bond. The other attributes for the two atoms include the timestep
during which the bond broke and the current/initial center of mass
position of the two atoms.
local data to be accessed by other LAMMPS commands. Following this optional
keyword, a list of one or more attributes is specified. These include the
IDs of the two atoms in the bond. The other attributes for the two atoms
include the timestep during which the bond broke and the current/initial
center of mass position of the two atoms.
Data is continuously accumulated over intervals of *N*
timesteps. At the end of each interval, all of the saved accumulated
@ -177,29 +176,38 @@ Restart and other info
This bond style writes the reference state of each bond to
:doc:`binary restart files <restart>`. Loading a restart file will
properly resume bonds.
properly resume bonds. However, the reference state is NOT
written to data files. Therefore reading a data file will not
restore bonds and will cause their reference states to be redefined.
The single() function of these pair styles returns 0.0 for the energy
of a pairwise interaction, since energy is not conserved in these
dissipative potentials. It also returns only the normal component of
the pairwise interaction force.
The accumulated data is not written to restart files and should be
output before a restart file is written to avoid missing data.
The internal fix calculates a local vector or local array depending on the
number of input values. The length of the vector or number of rows in
the array is the number of recorded, lost interactions. If a single
input is specified, a local vector is produced. If two or more inputs
are specified, a local array is produced where the number of columns =
the number of inputs. The vector or array can be accessed by any
command that uses local values from a compute as input. See the
:doc:`Howto output <Howto_output>` page for an overview of LAMMPS
output options.
If the *store/local* option is used, an internal fix will calculate
a local vector or local array depending on the number of input values.
The length of the vector or number of rows in the array is the number
of recorded, broken bonds. If a single input is specified, a local
vector is produced. If two or more inputs are specified, a local array
is produced where the number of columns = the number of inputs. The
vector or array can be accessed by any command that uses local values
from a compute as input. See the :doc:`Howto output <Howto_output>` page
for an overview of LAMMPS output options.
The vector or array will be floating point values that correspond to
the specified attribute.
The single() function of this bond style returns 0.0 for the energy
of a bonded interaction, since energy is not conserved in these
dissipative potentials. It also returns only the normal component of
the bonded interaction force. However, the single() function also
calculates 7 extra bond quantities. The first 4 are data from the
reference state of the bond including the initial distance between particles
:math:`r_0` followed by the :math:`x`, :math:`y`, and :math:`z` components
of the initial unit vector pointing to particle I from particle J. The next 3
quantities (5-7) are the :math:`x`, :math:`y`, and :math:`z` components
of the total force, including normal and tangential contributions, acting
on particle I.
These extra quantities can be accessed by the :doc:`compute bond/local <compute_bond_local>`
command, as *b1*, *b2*, ..., *b7*\ .
Restrictions
""""""""""""

49
doc/src/bond_bpm_spring.rst
View File

@ -103,15 +103,14 @@ the *overlay/pair* keyword. These settings require specific
restrictions. Further details can be found in the `:doc: how to
<Howto_BPM>` page on BPMs.
If the *store/local* keyword is used, this fix will track bonds that
If the *store/local* keyword is used, an internal fix will track bonds that
break during the simulation. Whenever a bond breaks, data is processed
and transferred to an internal fix labeled *fix_ID*. This allows the
local data to be accessed by other LAMMPS commands.
Following any optional keyword/value arguments, a list of one or more
attributes is specified. These include the IDs of the two atoms in
the bond. The other attributes for the two atoms include the timestep
during which the bond broke and the current/initial center of mass
position of the two atoms.
local data to be accessed by other LAMMPS commands. Following this optional
keyword, a list of one or more attributes is specified. These include the
IDs of the two atoms in the bond. The other attributes for the two atoms
include the timestep during which the bond broke and the current/initial
center of mass position of the two atoms.
Data is continuously accumulated over intervals of *N*
timesteps. At the end of each interval, all of the saved accumulated
@ -141,28 +140,30 @@ Restart and other info
This bond style writes the reference state of each bond to
:doc:`binary restart files <restart>`. Loading a restart
file will properly resume bonds.
file will properly restore bonds. However, the reference state is NOT
written to data files. Therefore reading a data file will not
restore bonds and will cause their reference states to be redefined.
The single() function of these pair styles returns 0.0 for the energy
of a pairwise interaction, since energy is not conserved in these
dissipative potentials.
The accumulated data is not written to restart files and should be
output before a restart file is written to avoid missing data.
The internal fix calculates a local vector or local array depending on the
number of input values. The length of the vector or number of rows in
the array is the number of recorded, lost interactions. If a single
input is specified, a local vector is produced. If two or more inputs
are specified, a local array is produced where the number of columns =
the number of inputs. The vector or array can be accessed by any
command that uses local values from a compute as input. See the
:doc:`Howto output <Howto_output>` page for an overview of LAMMPS
output options.
If the *store/local* option is used, an internal fix will calculate
a local vector or local array depending on the number of input values.
The length of the vector or number of rows in the array is the number
of recorded, broken bonds. If a single input is specified, a local
vector is produced. If two or more inputs are specified, a local array
is produced where the number of columns = the number of inputs. The
vector or array can be accessed by any command that uses local values
from a compute as input. See the :doc:`Howto output <Howto_output>` page
for an overview of LAMMPS output options.
The vector or array will be floating point values that correspond to
the specified attribute.
The single() function of this bond style returns 0.0 for the energy
of a bonded interaction, since energy is not conserved in these
dissipative potentials. The single() function also calculates an
extra bond quantity, the initial distance :math:`r_0`. This
extra quantity can be accessed by the
:doc:`compute bond/local <compute_bond_local>` command as *b1*\ .
Restrictions
""""""""""""

2
doc/src/bond_coeff.rst
View File

@ -21,7 +21,7 @@ Examples
bond_coeff 5 80.0 1.2
bond_coeff * 30.0 1.5 1.0 1.0
bond_coeff 1*4 30.0 1.5 1.0 1.0
bond_coeff 1 harmonic 200.0 1.0 (for bond_style hybrid)
bond_coeff 1 harmonic 200.0 1.0 # (for bond_style hybrid)
labelmap bond 5 carbonyl
bond_coeff carbonyl 80.0 1.2

10
doc/src/bond_mm3.rst
View File

@ -26,14 +26,14 @@ as defined in :ref:`(Allinger) <mm3-allinger1989>`
.. math::
E = K (r - r_0)^2 \left[ 1 - 2.55(r-r_0) + (7/12) 2.55^2(r-r_0)^2 \right]
E = K (r - r_0)^2 \left[ 1 - 2.55(r-r_0) + \frac{7}{12} 2.55^2(r-r_0)^2 \right]
where :math:`r_0` is the equilibrium value of the bond, and :math:`K` is a
prefactor. The anharmonic prefactors have units angstrom\^(-n):
-2.55 angstrom\^(-1) and (7/12)2.55\^2 angstrom\^(-2). The code takes
prefactor. The anharmonic prefactors have units :math:`\AA^{-n}`:
:math:`-2.55 \AA^{-1}` and :math:`\frac{7}{12} 2.55^2 \AA^{-2}`. The code takes
care of the necessary unit conversion for these factors internally.
Note that the MM3 papers contains an error in Eq (1):
(7/12)2.55 should be replaced with (7/12)2.55\^2
Note that the MM3 papers contain an error in Eq (1):
:math:`\frac{7}{12} 2.55` should be replaced with :math:`\frac{7}{12} 2.55^2`
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in

19
doc/src/bond_quartic.rst
View File

@ -28,11 +28,18 @@ The *quartic* bond style uses the potential
.. math::
E = K (r - R_c)^ 2 (r - R_c - B_1) (r - R_c - B_2) + U_0 + 4 \epsilon \left[ \left(\frac{\sigma}{r}\right)^{12} - \left(\frac{\sigma}{r}\right)^6 \right] + \epsilon
E & = E_q + E_{LJ} \\
E_q & = K (r - R_c)^ 2 (r - R_c - B_1) (r - R_c - B_2) + U_0 \\
E_{LJ} & = \left\{ \begin{array} {l@{\quad:\quad}l}
4 \epsilon \left[ \left(\frac{\sigma}{r}\right)^{12} - \left(\frac{\sigma}{r}\right)^6 \right] + \epsilon & r < 2^{\frac{1}{6}}, \epsilon = 1, \sigma = 1 \\
0 & r >= 2^{\frac{1}{6}}
\end{array} \right.
to define a bond that can be broken as the simulation proceeds (e.g.
due to a polymer being stretched). The :math:`\sigma` and :math:`\epsilon` used in the
LJ portion of the formula are both set equal to 1.0 by LAMMPS.
due to a polymer being stretched). The :math:`\sigma` and
:math:`\epsilon` used in the LJ portion of the formula are both set
equal to 1.0 by LAMMPS and the LJ portion is cut off at its minimum,
i.e. at :math:`r_c = 2^{\frac{1}{6}}`.
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
@ -46,9 +53,9 @@ or :doc:`read_restart <read_restart>` commands:
* :math:`U_0` (energy)
This potential was constructed to mimic the FENE bond potential for
coarse-grained polymer chains. When monomers with :math:`\sigma = \epsilon = 1.0`
are used, the following choice of parameters gives a quartic potential that
looks nearly like the FENE potential:
coarse-grained polymer chains. When monomers with :math:`\sigma =
\epsilon = 1.0` are used, the following choice of parameters gives a
quartic potential that looks nearly like the FENE potential:
.. math::

15
doc/src/clear.rst
View File

@ -23,15 +23,16 @@ Description
"""""""""""
This command deletes all atoms, restores all settings to their default
values, and frees all memory allocated by LAMMPS. Once a clear
command has been executed, it is almost as if LAMMPS were starting
over, with only the exceptions noted below. This command enables
multiple jobs to be run sequentially from one input script.
values, and frees all memory allocated by LAMMPS. Once a clear command
has been executed, it is almost as if LAMMPS were starting over, with
only the exceptions noted below. This command enables multiple jobs to
be run sequentially from one input script.
These settings are not affected by a clear command: the working
directory (:doc:`shell <shell>` command), log file status
(:doc:`log <log>` command), echo status (:doc:`echo <echo>` command), and
input script variables (:doc:`variable <variable>` command).
directory (:doc:`shell <shell>` command), log file status (:doc:`log
<log>` command), echo status (:doc:`echo <echo>` command), and input
script variables except for *atomfile* style variables (:doc:`variable
<variable>` command).
Restrictions
""""""""""""

2
doc/src/compute_ave_sphere_atom.rst
View File

@ -35,6 +35,8 @@ Examples
Description
"""""""""""
.. versionadded:: 7Jan2022
Define a computation that calculates the local mass density and
temperature for each atom based on its neighbors inside a spherical
cutoff. If an atom has :math:`M` neighbors, then its local mass density is

18
doc/src/compute_bond_local.rst
View File

@ -13,7 +13,7 @@ Syntax
* ID, group-ID are documented in :doc:`compute <compute>` command
* bond/local = style name of this compute command
* one or more values may be appended
* value = *dist* or *dx* or *dy* or *dz* or *engpot* or *force* or *fx* or *fy* or *fz* or *engvib* or *engrot* or *engtrans* or *omega* or *velvib* or *v_name*
* value = *dist* or *dx* or *dy* or *dz* or *engpot* or *force* or *fx* or *fy* or *fz* or *engvib* or *engrot* or *engtrans* or *omega* or *velvib* or *v_name* or *bN*
.. parsed-literal::
@ -29,6 +29,7 @@ Syntax
*omega* = magnitude of bond angular velocity
*velvib* = vibrational velocity along the bond length
*v_name* = equal-style variable with name (see below)
*bN* = bond style specific quantities for allowed N values
* zero or more keyword/args pairs may be appended
* keyword = *set*
@ -47,7 +48,7 @@ Examples
compute 1 all bond/local engpot
compute 1 all bond/local dist engpot force
compute 1 all bond/local dist fx fy fz
compute 1 all bond/local dist fx fy fz b1 b2
compute 1 all bond/local dist v_distsq set dist d
@ -147,6 +148,19 @@ those quantities via the :doc:`compute reduce <compute_reduce>` command
with thermo output, and the :doc:`fix ave/histo <fix_ave_histo>`
command will histogram the length\ :math:`^2` values and write them to a file.
A bond style may define additional bond quantities which can be
accessed as *b1* to *bN*, where N is defined by the bond style. Most
bond styles do not define any additional quantities, so N = 0. An
example of ones that do are the :doc:`BPM bond styles <Howto_bpm>`
which store the reference state between two particles. See
individual bond styles for details.
When using *bN* with bond style *hybrid*, the output will be the Nth
quantity from the sub-style that computes the bonded interaction
(based on bond type). If that sub-style does not define a *bN*,
the output will be 0.0. The maximum allowed N is the maximum number
of quantities provided by any sub-style.
----------
The local data stored by this command is generated by looping over all

3
doc/src/compute_chunk_atom.rst
View File

@ -602,8 +602,7 @@ be used. For non-orthogonal (triclinic) simulation boxes, only the
*reduced* option may be used.
A *box* value selects standard distance units as defined by the
:doc:`units <units>` command (e.g., :math:`\mathrm{\mathring A}`
for units = *real* or *metal*).
:doc:`units <units>` command (e.g., :math:`\AA` for units = *real* or *metal*).
A *lattice* value means the distance units are in lattice spacings.
The :doc:`lattice <lattice>` command must have been previously used to
define the lattice spacing. A *reduced* value means normalized

16
doc/src/compute_damage_atom.rst
View File

@ -24,16 +24,17 @@ Description
"""""""""""
Define a computation that calculates the per-atom damage for each atom
in a group. This is a quantity relevant for :doc:`Peridynamics models <pair_peri>`. See `this document <PDF/PDLammps_overview.pdf>`_
for an overview of LAMMPS commands for Peridynamics modeling.
in a group. This is a quantity relevant for :doc:`Peridynamics models
<pair_peri>`. See `this document <PDF/PDLammps_overview.pdf>`_ for an
overview of LAMMPS commands for Peridynamics modeling.
The "damage" of a Peridynamics particles is based on the bond breakage
between the particle and its neighbors. If all the bonds are broken
the particle is considered to be fully damaged.
See the `PDLAMMPS user guide <http://www.sandia.gov/~mlparks/papers/PDLAMMPS.pdf>`_ for a formal
definition of "damage" and more details about Peridynamics as it is
implemented in LAMMPS.
See the :doc:`Peridynamics Howto <Howto_peri>` for a formal definition
of "damage" and more details about Peridynamics as it is implemented in
LAMMPS.
This command can be used with all the Peridynamic pair styles.
@ -53,8 +54,9 @@ The per-atom vector values are unitless numbers (damage) :math:`\ge 0.0`.
Restrictions
""""""""""""
This compute is part of the PERI package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package <Build_package>` page for more info.
This compute is part of the PERI package. It is only enabled if LAMMPS
was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
Related commands
""""""""""""""""

20
doc/src/compute_dilatation_atom.rst
View File

@ -24,7 +24,8 @@ Description
"""""""""""
Define a computation that calculates the per-atom dilatation for each
atom in a group. This is a quantity relevant for :doc:`Peridynamics models <pair_peri>`. See `this document <PDF/PDLammps_overview.pdf>`_
atom in a group. This is a quantity relevant for :doc:`Peridynamics
models <pair_peri>`. See `this document <PDF/PDLammps_overview.pdf>`_
for an overview of LAMMPS commands for Peridynamics modeling.
For small deformation, dilatation of is the measure of the volumetric
@ -32,13 +33,14 @@ strain.
The dilatation :math:`\theta` for each peridynamic particle :math:`i` is
calculated as a sum over its neighbors with unbroken bonds, where the
contribution of the :math:`ij` pair is a function of the change in bond length
(versus the initial length in the reference state), the volume
contribution of the :math:`ij` pair is a function of the change in bond
length (versus the initial length in the reference state), the volume
fraction of the particles and an influence function. See the
`PDLAMMPS user guide <http://www.sandia.gov/~mlparks/papers/PDLAMMPS.pdf>`_ for
a formal definition of dilatation.
:doc:`Peridynamics Howto <Howto_peri>` for a formal definition of
dilatation.
This command can only be used with a subset of the Peridynamic :doc:`pair styles <pair_peri>`: peri/lps, peri/ves and peri/eps.
This command can only be used with a subset of the Peridynamic
:doc:`pair styles <pair_peri>`: *peri/lps*, *peri/ves*, and *peri/eps*.
The dilatation value will be 0.0 for atoms not in the specified
compute group.
@ -56,9 +58,9 @@ The per-atom vector values are unitless numbers :math:`(\theta \ge 0.0)`.
Restrictions
""""""""""""
This compute is part of the PERI package. It is only enabled if
LAMMPS was built with that package. See the
:doc:`Build package <Build_package>` page for more info.
This compute is part of the PERI package. It is only enabled if LAMMPS
was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
Related commands
""""""""""""""""

4
doc/src/compute_displace_atom.rst
View File

@ -17,7 +17,7 @@ Syntax
.. parsed-literal::
*replace* arg = name of per-atom variable
*refresh* arg = name of per-atom variable
Examples
""""""""
@ -95,7 +95,7 @@ something like the following commands:
refresh c_dsp delay 100
The :doc:`dump_modify thresh <dump_modify>` command will only output
atoms that have displaced more than :math:`0.6~\mathrm{\mathring A}` on each
atoms that have displaced more than :math:`0.6~\AA` on each
snapshot (assuming metal units). The dump_modify *refresh* option triggers a
call to this compute at the end of every dump.

4
doc/src/compute_entropy_atom.rst
View File

@ -97,13 +97,13 @@ by the corresponding volume. This option can be useful when dealing with
inhomogeneous systems such as those that have surfaces.
Here are typical input parameters for fcc aluminum (lattice
constant :math:`4.05~\mathrm{\mathring A}`),
constant :math:`4.05~\AA`),
.. parsed-literal::
compute 1 all entropy/atom 0.25 5.7 avg yes 3.7
and for bcc sodium (lattice constant 4.23 Angstroms),
and for bcc sodium (lattice constant :math:`4.23~\AA`),
.. parsed-literal::

2
doc/src/compute_fep_ta.rst
View File

@ -34,6 +34,8 @@ Examples
Description
"""""""""""
.. versionadded:: 4May2022
Define a computation that calculates the change in the free energy due
to a test-area (TA) perturbation :ref:`(Gloor) <Gloor>`. The test-area
approach can be used to determine the interfacial tension of the system

22
doc/src/compute_rigid_local.rst
View File

@ -6,7 +6,7 @@ compute rigid/local command
Syntax
""""""
.. parsed-literal::
.. code-block:: LAMMPS
compute ID group-ID rigid/local rigidID input1 input2 ...
@ -25,6 +25,9 @@ Syntax
quatw, quati, quatj, quatk,
tqx, tqy, tqz,
inertiax, inertiay, inertiaz
.. parsed-literal::
id = atom ID of atom within body which owns body properties
mol = molecule ID used to define body in :doc:`fix rigid/small <fix_rigid>` command
mass = total mass of body
@ -69,8 +72,8 @@ the atoms owned on a processor. If the atom is not in the specified
the atom within a body that is assigned to store the body information
it is skipped (only one atom per body is so assigned). If it is the
assigned atom, then the info for that body is output. This means that
information for N bodies is generated. N may be less than the # of
bodies defined by the fix rigid command, if the atoms in some bodies
information for :math:`N` bodies is generated. :math:`N` may be less than the
number of bodies defined by the fix rigid command, if the atoms in some bodies
are not in the *group-ID*\ .
.. note::
@ -109,8 +112,7 @@ The *mass* attribute is the total mass of the rigid body.
There are two options for outputting the coordinates of the center of
mass (COM) of the body. The *x*, *y*, *z* attributes write the COM
"unscaled", in the appropriate distance :doc:`units <units>`
(:math:`\mathrm{\mathring A}`,
sigma, etc). Use *xu*, *yu*, *zu* if you want the COM "unwrapped" by
(:math:`\AA`, :math:`\sigma`, etc). Use *xu*, *yu*, *zu* if you want the COM "unwrapped" by
the image flags for each body. Unwrapped means that if the body
COM has passed through a periodic boundary one or more times, the value
is generated what the COM coordinate would be if it had not been
@ -120,7 +122,7 @@ The image flags for the body can be generated directly using the *ix*,
*iy*, *iz* attributes. For periodic dimensions, they specify which
image of the simulation box the COM is considered to be in. An image
of 0 means it is inside the box as defined. A value of 2 means add 2
box lengths to get the true value. A value of -1 means subtract 1 box
box lengths to get the true value. A value of :math:`-1` means subtract 1 box
length to get the true value. LAMMPS updates these flags as the rigid
body COMs cross periodic boundaries during the simulation.
@ -142,8 +144,8 @@ The *tqx*, *tqy*, *tqz* attributes are components of the torque acting
on the body around its COM.
The *inertiax*, *inertiay*, *inertiaz* attributes are components of
diagonalized inertia tensor for the body, i.e the 3 moments of inertia
for the body around its principal axes, as computed internally by
diagonalized inertia tensor for the body (i.e., the three moments of inertia
for the body around its principal axes), as computed internally by
LAMMPS.
----------
@ -170,10 +172,10 @@ corresponding attribute is in:
* vx,vy,vz = velocity units
* fx,fy,fz = force units
* omegax,omegay,omegaz = radians/time units
* angmomx,angmomy,angmomz = mass\*distance\^2/time units
* angmomx,angmomy,angmomz = mass\*distance\ :math:`^2`\ /time units
* quatw,quati,quatj,quatk = unitless
* tqx,tqy,tqz = torque units
* inertiax,inertiay,inertiaz = mass\*distance\^2 units
* inertiax,inertiay,inertiaz = mass\*distance\ :math:`^2` units
Restrictions
""""""""""""

2
doc/src/compute_saed.rst
View File

@ -86,7 +86,7 @@ will defined using the *c* values for the spacing along each reciprocal
lattice axis. Note that manual mapping of the reciprocal space mesh is
good for comparing diffraction results from multiple simulations; however
it can reduce the likelihood that Bragg reflections will be satisfied
unless small spacing parameters (:math:`<0.05~\mathrm{\mathring A}^-1`)
unless small spacing parameters (:math:`<0.05~\AA^-1`)
are implemented. Meshes with manual spacing do not require a periodic
boundary.

24
doc/src/compute_sna_atom.rst
View File

@ -228,18 +228,20 @@ command:
See section below on output for a detailed explanation of the data
layout in the global array.
.. versionadded:: 3Aug2022
The compute *sna/grid* and *sna/grid/local* commands calculate
bispectrum components for a regular grid of points.
These are calculated from the local density of nearby atoms *i'*
around each grid point, as if there was a central atom *i*
at the grid point. This is useful for characterizing fine-scale
structure in a configuration of atoms, and it is used
in the `MALA package <https://github.com/casus/mala>`_
to build machine-learning surrogates for finite-temperature Kohn-Sham
density functional theory (:ref:`Ellis et al. <Ellis2021>`)
Neighbor atoms not in the group do not contribute to the
bispectrum components of the grid points. The distance cutoff :math:`R_{ii'}`
assumes that *i* has the same type as the neighbor atom *i'*.
bispectrum components for a regular grid of points. These are
calculated from the local density of nearby atoms *i'* around each grid
point, as if there was a central atom *i* at the grid point. This is
useful for characterizing fine-scale structure in a configuration of
atoms, and it is used in the `MALA package
<https://github.com/casus/mala>`_ to build machine-learning surrogates
for finite-temperature Kohn-Sham density functional theory (:ref:`Ellis
et al. <Ellis2021>`) Neighbor atoms not in the group do not contribute
to the bispectrum components of the grid points. The distance cutoff
:math:`R_{ii'}` assumes that *i* has the same type as the neighbor atom
*i'*.
Compute *sna/grid* calculates a global array containing bispectrum
components for a regular grid of points.

6
doc/src/compute_temp_cs.rst
View File

@ -29,7 +29,7 @@ Description
Define a computation that calculates the temperature of a system based
on the center-of-mass velocity of atom pairs that are bonded to each
other. This compute is designed to be used with the adiabatic
core/shell model of :ref:`(Mitchell and Finchham) <MitchellFinchham1>`.
core/shell model of :ref:`(Mitchell and Fincham) <MitchellFincham1>`.
See the :doc:`Howto coreshell <Howto_coreshell>` page for an overview of
the model as implemented in LAMMPS. Specifically, this compute
enables correct temperature calculation and thermostatting of
@ -127,7 +127,7 @@ none
----------
.. _MitchellFinchham1:
.. _MitchellFincham1:
**(Mitchell and Finchham)** Mitchell, Finchham, J Phys Condensed Matter,
**(Mitchell and Fincham)** Mitchell, Fincham, J Phys Condensed Matter,
5, 1031-1038 (1993).

2
doc/src/compute_temp_ramp.rst
View File

@ -58,7 +58,7 @@ constant, and :math:`T` is the absolute temperature.
The *units* keyword determines the meaning of the distance units used
for coordinates (*clo*, *chi*) and velocities (*vlo*, *vhi*). A *box* value
selects standard distance units as defined by the :doc:`units <units>`
command (e.g., :math:`\mathrm{\mathring{A}}` for units = real or metal). A
command (e.g., :math:`\AA` for units = real or metal). A
*lattice* value means the distance units are in lattice spacings (i.e.,
velocity in lattice spacings per unit time). The :doc:`lattice <lattice>`
command must have been previously used to define the lattice spacing.

34
doc/src/compute_voronoi_atom.rst
View File

@ -13,7 +13,7 @@ Syntax
* ID, group-ID are documented in :doc:`compute <compute>` command
* voronoi/atom = style name of this compute command
* zero or more keyword/value pairs may be appended
* keyword = *only_group* or *surface* or *radius* or *edge_histo* or *edge_threshold* or *face_threshold* or *neighbors* or *peratom*
* keyword = *only_group* or *occupation* or *surface* or *radius* or *edge_histo* or *edge_threshold* or *face_threshold* or *neighbors* or *peratom*
.. parsed-literal::
@ -154,25 +154,25 @@ which must be installed on your system when building LAMMPS for use
with this compute. See instructions on obtaining and installing the
Voro++ software in the src/VORONOI/README file.
.. _voronoi: http://math.lbl.gov/voro++/
.. _voronoi: https://math.lbl.gov/voro++/
.. note::
The calculation of Voronoi volumes is performed by each
processor for the atoms it owns, and includes the effect of ghost
atoms stored by the processor. This assumes that the Voronoi cells of
owned atoms are not affected by atoms beyond the ghost atom cut-off
distance. This is usually a good assumption for liquid and solid
systems, but may lead to underestimation of Voronoi volumes in low
density systems. By default, the set of ghost atoms stored by each
processor is determined by the cutoff used for
:doc:`pair_style <pair_style>` interactions. The cutoff can be set
explicitly via the :doc:`comm_modify cutoff <comm_modify>` command. The
Voronoi cells for atoms adjacent to empty regions will extend into
those regions up to the communication cutoff in :math:`x`, :math:`y`, or
:math:`z`. In that situation, an exterior face is created at the cutoff
distance normal to the :math:`x`, :math:`y`, or :math:`z` direction.
For triclinic systems, the exterior face is parallel to the corresponding
The calculation of Voronoi volumes is performed by each processor for
the atoms it owns, and includes the effect of ghost atoms stored by
the processor. This assumes that the Voronoi cells of owned atoms
are not affected by atoms beyond the ghost atom cut-off distance.
This is usually a good assumption for liquid and solid systems, but
may lead to underestimation of Voronoi volumes in low density
systems. By default, the set of ghost atoms stored by each processor
is determined by the cutoff used for :doc:`pair_style <pair_style>`
interactions. The cutoff can be set explicitly via the
:doc:`comm_modify cutoff <comm_modify>` command. The Voronoi cells
for atoms adjacent to empty regions will extend into those regions up
to the communication cutoff in :math:`x`, :math:`y`, or :math:`z`.
In that situation, an exterior face is created at the cutoff distance
normal to the :math:`x`, :math:`y`, or :math:`z` direction. For
triclinic systems, the exterior face is parallel to the corresponding
reciprocal lattice vector.
.. note::

2
doc/src/compute_xrd.rst
View File

@ -91,7 +91,7 @@ reciprocal lattice axis. Note that manual mapping of the reciprocal
space mesh is good for comparing diffraction results from multiple
simulations; however, it can reduce the likelihood that Bragg
reflections will be satisfied unless small spacing parameters
(:math:`< 0.05~\mathrm{\mathring{A}}^{-1}`) are implemented.
(:math:`< 0.05~\AA^{-1}`) are implemented.
Meshes with manual spacing do not require a periodic boundary.
The limits of the reciprocal lattice mesh are determined by range of

8
doc/src/create_atoms.rst
View File

@ -28,7 +28,7 @@ Syntax
region-ID = create atoms within this region, use NULL for entire simulation box
* zero or more keyword/value pairs may be appended
* keyword = *mol* or *basis* or *ratio* or *subset* or *remap* or *var* or *set* or *rotate* or *overlap* or *maxtry* or *units*
* keyword = *mol* or *basis* or *ratio* or *subset* or *remap* or *var* or *set* or *radscale* or *meshmode* or *rotate* or *overlap* or *maxtry* or *units*
.. parsed-literal::
@ -189,6 +189,10 @@ to the area of that triangle.
beneficial to exclude computing interactions between the created
particles using :doc:`neigh_modify exclude <neigh_modify>`.
.. versionchanged:: 2Jun2022
The *porosity* style has been renamed to *random* with added functionality.
For the *random* style, *N* particles are added to the system at
randomly generated coordinates, which can be useful for generating an
amorphous system. The particles are created one by one using the
@ -460,7 +464,7 @@ The *units* keyword determines the meaning of the distance units used
to specify the coordinates of the one particle created by the *single*
style, or the overlap distance *Doverlap* by the *overlap* keyword. A
*box* value selects standard distance units as defined by the
:doc:`units <units>` command (e.g., :math:`\mathrm{\mathring{A}}` for
:doc:`units <units>` command (e.g., :math:`\AA` for
units = *real* or *metal*\ . A *lattice* value means the distance units are in
lattice spacings.

2
doc/src/delete_atoms.rst
View File

@ -116,6 +116,8 @@ must be in both the specified group and region. If *group-ID* = all,
there is effectively no group criterion. If *region-ID* is specified
as NULL, no region criterion is imposed.
.. versionadded:: 4May2022
For style *variable*, all atoms for which the atom-style variable with
the given name evaluates to non-zero will be deleted. Additional atoms
can be deleted if they are in a molecule for which one or more atoms

11
doc/src/delete_bonds.rst
View File

@ -26,6 +26,13 @@ Syntax
* zero or more keywords may be appended
* keyword = *any* or *undo* or *remove* or *special*
.. parsed-literal::
*any* arg = none = turn off interactions if any atoms are in the group (or on if *undo* is also used)
*undo* arg = none = turn specified bonds on instead of off
*remove* arg = permanently remove bonds that have been turned off
*special* arg = recompute pairwise 1-2, 1-3, and 1-4 lists
Examples
""""""""
@ -101,13 +108,13 @@ Several keywords can be appended to the argument list to alter the
default behaviors.
The *any* keyword changes the requirement that all atoms in the bond
(angle, etc) must be in the specified group in order to turn off the
(angle, etc.) must be in the specified group in order to turn off the
interaction. Instead, if any of the atoms in the interaction are in
the specified group, it will be turned off (or on if the *undo*
keyword is used).
The *undo* keyword inverts the delete_bonds command so that the
specified bonds, angles, etc are turned on if they are currently
specified bonds, angles, etc. are turned on if they are currently
turned off. This means a negative value is toggled to positive. For
example, for style *angle*, if *type* is specified as 2, then all
angles with current type = :math:`-2` are reset to type = :math:`2`.

2
doc/src/displace_atoms.rst
View File

@ -104,7 +104,7 @@ atom's rotation.
Distance units for displacements and the origin point of the *rotate*
style are determined by the setting of *box* or *lattice* for the
*units* keyword. *Box* means distance units as defined by the
:doc:`units <units>` command (e.g., :math:`\mathrm{\mathring A}` for
:doc:`units <units>` command (e.g., :math:`\AA` for
*real* or *metal* units). *Lattice* means distance units are in lattice
spacings. The :doc:`lattice <lattice>` command must have been previously used
to define the lattice spacing.

6
doc/src/dump.rst
View File

@ -202,7 +202,7 @@ or multiple smaller files).
to a dump file may be slightly outside the simulation box.
Re-neighbor timesteps will not typically coincide with the
timesteps dump snapshots are written. See the :doc:`dump_modify
pbc <dump_modify>` command if you with to force coordinates to be
pbc <dump_modify>` command if you wish to force coordinates to be
strictly inside the simulation box.
.. note::
@ -480,7 +480,7 @@ style.
----------
Note that *atom*, *custom*, *dcd*, *xtc*, and *xyz* style dump files
can be read directly by `VMD <http://www.ks.uiuc.edu/Research/vmd>`_, a
can be read directly by `VMD <https://www.ks.uiuc.edu/Research/vmd>`_, a
popular molecular viewing program.
----------
@ -693,7 +693,7 @@ charge.
There are several options for outputting atom coordinates. The *x*,
*y*, and *z* attributes write atom coordinates "unscaled", in the
appropriate distance :doc:`units <units>` (:math:`\mathrm{\mathring A}`,
appropriate distance :doc:`units <units>` (:math:`\AA`,
:math:`\sigma`, etc.). Use *xs*, *ys*, and *zs* if you want the
coordinates "scaled" to the box size so that each value is 0.0 to 1.0.
If the simulation box is triclinic (tilted), then all atom coords will

6
doc/src/dump_h5md.rst
View File

@ -64,7 +64,7 @@ stored within the same file by defining several dumps. A dump that
refers (via *file_from*) to an already open dump ID and that concerns
another particle group must specify *create_group yes*.
.. _h5md: http://nongnu.org/h5md/
.. _h5md: https://nongnu.org/h5md/
Each data element is written every N\*N_element steps. For *image*, no
sub-interval is needed as it must be present at the same interval as
@ -113,7 +113,7 @@ the `HDF5 <HDF5-ws_>`_ library installed (C bindings are sufficient) on
your system. The library ch5md is compiled with the h5cc wrapper
provided by the HDF5 library.
.. _HDF5-ws: http://www.hdfgroup.org/HDF5/
.. _HDF5-ws: https://www.hdfgroup.org/solutions/hdf5/
----------
@ -129,4 +129,4 @@ Related commands
**(de Buyl)** de Buyl, Colberg and Hofling, H5MD: A structured,
efficient, and portable file format for molecular data,
Comp. Phys. Comm. 185(6), 1546-1553 (2014) -
`[arXiv:1308.6382] <http://arxiv.org/abs/1308.6382/>`_.
`[arXiv:1308.6382] <https://arxiv.org/abs/1308.6382/>`_.

4
doc/src/dump_image.rst
View File

@ -212,7 +212,7 @@ is used.
Similarly, the format of the resulting movie is chosen with the
*movie* dump style. This is handled by the underlying FFmpeg converter
and thus details have to be looked up in the `FFmpeg documentation
<http://ffmpeg.org/ffmpeg.html>`_. Typical examples are: .avi, .mpg,
<https://ffmpeg.org/ffmpeg.html>`_. Typical examples are: .avi, .mpg,
.m4v, .mp4, .mkv, .flv, .mov, .gif Additional settings of the movie
compression like bitrate and framerate can be set using the
dump_modify command as described below.
@ -642,7 +642,7 @@ MPEG or other movie file you can use:
cat snap.*.ppm | ffmpeg -y -f image2pipe -c:v ppm -i - -b:v 2400k movie.avi
Front ends for FFmpeg exist for multiple platforms. For more
information see the `FFmpeg homepage <http://www.ffmpeg.org/>`_
information see the `FFmpeg homepage <https://www.ffmpeg.org/>`_
----------

14
doc/src/dump_modify.rst
View File

@ -17,7 +17,7 @@ Syntax
* one or more keyword/value pairs may be appended
* these keywords apply to various dump styles
* keyword = *append* or *at* or *balance* or *buffer* or *delay* or *element* or *every* or *every/time* or *fileper* or *first* or *flush* or *format* or *header* or *image* or *label* or *maxfiles* or *nfile* or *pad* or *pbc* or *precision* or *region* or *refresh* or *scale* or *sfactor* or *skip* or *sort* or *tfactor* or *thermo* or *thresh* or *time* or *units* or *unwrap*
* keyword = *append* or *at* or *balance* or *buffer* or *colname* or *delay* or *element* or *every* or *every/time* or *fileper* or *first* or *flush* or *format* or *header* or *image* or *label* or *maxfiles* or *nfile* or *pad* or *pbc* or *precision* or *region* or *refresh* or *scale* or *sfactor* or *skip* or *sort* or *tfactor* or *thermo* or *thresh* or *time* or *units* or *unwrap*
.. parsed-literal::
@ -181,8 +181,8 @@ extra buffering.
.. versionadded:: 4May2022
The *colname* keyword can be used to change the default header keyword
for dump styles: *atom*, *custom*, and *cfg* and their compressed, ADIOS,
and MPIIO variants. The setting for *ID string* replaces the default
for dump styles: *atom*, *custom*, *cfg*, and *local* and their compressed,
ADIOS, and MPIIO variants. The setting for *ID string* replaces the default
text with the provided string. *ID* can be a positive integer when it
represents the column number counting from the left, a negative integer
when it represents the column number from the right (i.e. -1 is the last
@ -632,7 +632,7 @@ calculates the displacement of each atom from its reference position.
The "4" index is the scalar displacement; 1, 2, and 3 are the :math:`xyz`
components of the displacement. The :doc:`dump_modify thresh <dump_modify>`
command will cause only atoms that have displaced more than
:math:`0.6~\mathrm{\mathring A}` to be output on a given snapshot (assuming
:math:`0.6~\AA` to be output on a given snapshot (assuming
metal units). However, note that when an atom is output, we also need to
update the reference position for that atom to its new coordinates. So that it
will not be output in every snapshot thereafter. That reference position is
@ -675,7 +675,7 @@ value of *yes* means atom coords are written in normalized units from
0.0 to 1.0 in each box dimension. If the simulation box is triclinic
(tilted), then all atom coords will still be between 0.0 and 1.0. A
value of *no* means they are written in absolute distance units
(e.g., :math:`\mathrm{\mathring A}` or :math:`\sigma`).
(e.g., :math:`\AA` or :math:`\sigma`).
Using this keyword will reset all custom header names set with
*dump_modify colname* to their respective default values.
@ -687,7 +687,7 @@ when writing to XTC files. By default, they are initialized for
whatever :doc:`units <units>` style is being used, to write out
coordinates in nanometers and time in picoseconds. For example, for *real*
units, LAMMPS defines *sfactor* = 0.1 and *tfactor* = 0.001, since the
:math:`\mathrm{\mathring A}` and fs used by *real* units are 0.1 nm and
:math:`\AA` and fs used by *real* units are 0.1 nm and
0.001 ps, respectively. If you are using a units system with distance and time
units far from nm and ps, you may wish to write XTC files with
different units, since the compression algorithm used in XTC files is
@ -881,7 +881,7 @@ levels that sacrifice compression for performance. 0 is the default,
positive levels are 1 to 22, with 22 being the most expensive
compression. Zstd promises higher compression/decompression speeds for
similar compression ratios. For more details see
`http://facebook.github.io/zstd/`.
`https://facebook.github.io/zstd/`.
In addition, Zstd compressed files can include a checksum of the
entire contents. The Zstd enabled dump styles enable this feature by

2
doc/src/dump_molfile.rst
View File

@ -34,7 +34,7 @@ Dump a snapshot of atom coordinates and selected additional quantities
to one or more files every N timesteps in one of several formats.
Only information for atoms in the specified group is dumped. This
specific dump style uses molfile plugins that are bundled with the
`VMD <http://www.ks.uiuc.edu/Research/vmd>`_ molecular visualization and
`VMD <https://www.ks.uiuc.edu/Research/vmd>`_ molecular visualization and
analysis program.
Unless the filename contains a \* character, the output will be written

14
doc/src/dump_netcdf.rst
View File

@ -48,21 +48,17 @@ rank.
NetCDF files can be directly visualized via the following tools:
Ovito (http://www.ovito.org/). Ovito supports the AMBER convention and
all extensions of this dump style.
* VMD (http://www.ks.uiuc.edu/Research/vmd/).
* AtomEye (http://www.libatoms.org/). The libAtoms version of AtomEye
contains a NetCDF reader that is not present in the standard
distribution of AtomEye.
* Ovito (https://www.ovito.org/). Ovito supports the AMBER convention and
all extensions of this dump style.
* VMD (https://www.ks.uiuc.edu/Research/vmd/).
In addition to per-atom data, :doc:`thermo <thermo>` data can be included in the
dump file. The data included in the dump file is identical to the data specified
by :doc:`thermo_style <thermo_style>`.
.. _netcdf-home: http://www.unidata.ucar.edu/software/netcdf/
.. _netcdf-home: https://www.unidata.ucar.edu/software/netcdf/
.. _pnetcdf-home: http://trac.mcs.anl.gov/projects/parallel-netcdf/
.. _pnetcdf-home: https://trac.mcs.anl.gov/projects/parallel-netcdf/
----------

26
doc/src/dump_vtk.rst
View File

@ -29,8 +29,9 @@ Description
"""""""""""
Dump a snapshot of atom quantities to one or more files every :math:`N`
timesteps in a format readable by the `VTK visualization toolkit <http://www.vtk.org>`_ or other visualization tools that use it,
such as `ParaView <http://www.paraview.org>`_. The time steps on which dump
timesteps in a format readable by the `VTK visualization toolkit
<https://www.vtk.org>`_ or other visualization tools that use it, such
as `ParaView <https://www.paraview.org>`_. The time steps on which dump
output is written can also be controlled by a variable; see the
:doc:`dump_modify every <dump_modify>` command for details.
@ -38,8 +39,8 @@ This dump style is similar to :doc:`dump_style custom <dump>` but uses
the VTK library to write data to VTK simple legacy or XML format,
depending on the filename extension specified for the dump file. This
can be either *\*.vtk* for the legacy format or *\*.vtp* and *\*.vtu*,
respectively, for XML format; see the
`VTK homepage <http://www.vtk.org/VTK/img/file-formats.pdf>`_ for a detailed
respectively, for XML format; see the `VTK homepage
<https://www.vtk.org/VTK/img/file-formats.pdf>`_ for a detailed
description of these formats. Since this naming convention conflicts
with the way binary output is usually specified (see below), the
:doc:`dump_modify binary <dump_modify>` command allows setting of a
@ -61,14 +62,15 @@ determine the kind of output.
.. warning::
Unless the :doc:`dump_modify sort <dump_modify>` option
is invoked, the lines of atom information written to dump files will
be in an indeterminate order for each snapshot. This is even true
when running on a single processor, if the :doc:`atom_modify sort <atom_modify>` option is on, which it is by default. In this
case atoms are re-ordered periodically during a simulation, due to
spatial sorting. It is also true when running in parallel, because
data for a single snapshot is collected from multiple processors, each
of which owns a subset of the atoms.
Unless the :doc:`dump_modify sort <dump_modify>` option is invoked,
the lines of atom information written to dump files will be in an
indeterminate order for each snapshot. This is even true when
running on a single processor, if the :doc:`atom_modify sort
<atom_modify>` option is on, which it is by default. In this case
atoms are re-ordered periodically during a simulation, due to spatial
sorting. It is also true when running in parallel, because data for
a single snapshot is collected from multiple processors, each of
which owns a subset of the atoms.
For the *vtk* style, sorting is off by default. See the
:doc:`dump_modify <dump_modify>` page for details.

4
doc/src/fix_acks2_reaxff.rst
View File

@ -71,7 +71,7 @@ potential in eV, *gamma*, the valence orbital exponent, and *bcut*, the
bond cutoff distance. Note that these 4 quantities are also in the
ReaxFF potential file, except that eta is defined here as twice the eta
value in the ReaxFF file. Note that unlike the rest of LAMMPS, the units
of this fix are hard-coded to be :math:`\mathrm{\mathring{A}}`, eV, and
of this fix are hard-coded to be :math:`\AA`, eV, and
electronic charge.
The optional *maxiter* keyword allows changing the max number
@ -111,7 +111,7 @@ LAMMPS was built with that package. See the :doc:`Build package
This fix does not correctly handle interactions involving multiple
periodic images of the same atom. Hence, it should not be used for
periodic cell dimensions less than :math:`10~\mathrm{\mathring{A}}`.
periodic cell dimensions less than :math:`10~\AA`.
This fix may be used in combination with :doc:`fix efield <fix_efield>`
and will apply the external electric field during charge equilibration,

2
doc/src/fix_adapt.rst
View File

@ -319,6 +319,8 @@ with fix_adapt are
----------
.. versionadded:: 4May2022
The *angle* keyword uses the specified variable to change the value of
an angle coefficient over time, very similar to how the *pair* keyword
operates. The only difference is that now an angle coefficient for a

2
doc/src/fix_append_atoms.rst
View File

@ -79,7 +79,7 @@ measured from zhi and is set with the *extent* argument.
The *units* keyword determines the meaning of the distance units used
to define a wall position, but only when a numeric constant is used.
A *box* value selects standard distance units as defined by the
:doc:`units <units>` command (e.g., :math:`\mathrm{\mathring A}`
:doc:`units <units>` command (e.g., :math:`\AA`
for units = real or metal.
A *lattice* value means the distance units are in lattice spacings.
The :doc:`lattice <lattice>` command must have been previously used to

2
doc/src/fix_ave_chunk.rst
View File

@ -31,7 +31,7 @@ Syntax
v_name = per-atom vector calculated by an atom-style variable with name
* zero or more keyword/arg pairs may be appended
* keyword = *norm* or *ave* or *bias* or *adof* or *cdof* or *file* or *overwrite* or *title1* or *title2* or *title3*
* keyword = *norm* or *ave* or *bias* or *adof* or *cdof* or *file* or *overwrite* or *format* or *title1* or *title2* or *title3*
.. parsed-literal::

2
doc/src/fix_ave_histo.rst
View File

@ -35,7 +35,7 @@ Syntax
v_name[I] = value calculated by a vector-style variable with name, I can include wildcard (see below)
* zero or more keyword/arg pairs may be appended
* keyword = *mode* or *file* or *ave* or *start* or *beyond* or *overwrite* or *title1* or *title2* or *title3*
* keyword = *mode* or *kind* or *file* or *ave* or *start* or *beyond* or *overwrite* or *title1* or *title2* or *title3*
.. parsed-literal::

2
doc/src/fix_ave_time.rst
View File

@ -28,7 +28,7 @@ Syntax
v_name[I] = value calculated by a vector-style variable with name, I can include wildcard (see below)
* zero or more keyword/arg pairs may be appended
* keyword = *mode* or *file* or *ave* or *start* or *off* or *overwrite* or *title1* or *title2* or *title3*
* keyword = *mode* or *file* or *ave* or *start* or *off* or *overwrite* or *format* or *title1* or *title2* or *title3*
.. parsed-literal::

55
doc/src/fix_bocs.rst
View File

@ -6,17 +6,28 @@ fix bocs command
Syntax
""""""
.. parsed-literal::
.. code-block:: LAMMPS
fix ID group-ID bocs keyword values ...
fix ID group-ID bocs keyword values ...
* ID, group-ID are documented in :doc:`fix <fix>` command
* bocs = style name of this fix command
* two or more keyword/value pairs may be appended
* keyword = *temp* or *cgiso* or *tchain* or *pchain* or *mtk* or *tloop* or *ploop*
.. parsed-literal::
keyword = *temp* or *cgiso* or *analytic* or *linear_spline* or *cubic_spline*
*temp* values = Tstart Tstop Tdamp
*cgiso* values = Pstart Pstop Pdamp
*basis set*
*analytic* values = V_avg N_particles N_coeff Coeff_1 Coeff_2 ... Coeff_N
*linear_spline* values = input_filename
*cubic_spline* values = input_filename
*cgiso* values = Pstart Pstop Pdamp basis_set args
basis_set = *analytic* or *linear_spline* or *cubic_spline*
*analytic* args = V_avg N_particles N_coeff Coeff_1 Coeff_2 ... Coeff_N
*linear_spline* args = input_filename
*cubic_spline* args = input_filename
*tchain* value = N = length of thermostat chain (1 = single thermostat)
*pchain* value = N = length of thermostat on barostat (0 = no thermostat)
*mtk* value = *yes* or *no* = add MTK adjustment term or not
*tloop* value = M = number of sub-cycles to perform on thermostat
*ploop* value = M = number of sub-cycles to perform on barostat
Examples
""""""""
@ -24,25 +35,24 @@ Examples
.. code-block:: LAMMPS
fix 1 all bocs temp 300.0 300.0 100.0 cgiso 0.986 0.986 1000.0 analytic 66476.015 968 2 245030.10 8962.20
fix 1 all bocs temp 300.0 300.0 100.0 cgiso 0.986 0.986 1000.0 cubic_spline input_Fv.dat
thermo_modify press 1_press
Description
"""""""""""
These commands incorporate a pressure correction as described by
Dunn and Noid in :ref:`(Dunn1) <bocs-Dunn1>` to the standard MTTK
barostat by Martyna et. al. in :ref:`(Martyna) <bocs-Martyna>` .
The first half of the command mimics a standard fix npt command:
Dunn and Noid :ref:`(Dunn1) <bocs-Dunn1>` to the standard MTK
barostat by Martyna et al. :ref:`(Martyna) <bocs-Martyna>`.
The first half of the command mimics a standard :doc:`fix npt <fix_nh>`
command:
.. code-block:: LAMMPS
fix 1 all bocs temp Tstart Tstop Tcoupl cgiso Pstart Pstop Pdamp
The two differences are replacing *npt* with *bocs*, and replacing
*iso*\ /\ *aniso*\ /\ *etc* with *cgiso*\ .
*iso*\ /\ *aniso*\ /\ etc. with *cgiso*\ .
The rest of the command details what form you would like to use for
the pressure correction equation. The choices are: *analytic*, *linear_spline*,
or *cubic_spline*.
@ -58,9 +68,9 @@ as a function of volume. The file must be formatted so each line has:
Note both the COMMA and the SPACE separating the volume's
value and its corresponding pressure correction. The volumes in the file
must be uniformly spaced. Both the volumes and the pressure corrections
should be provided in the proper units, e.g. if you are using *units real*,
the volumes should all be in cubic angstroms, and the pressure corrections
should all be in atmospheres. Furthermore, the table should start/end at a
should be provided in the proper units (e.g., if you are using *units real*,
the volumes should all be in :math:`\mathrm{\mathring{A}}^3` and the pressure
corrections should all be in atm). Furthermore, the table should start/end at a
volume considerably smaller/larger than you expect your system to sample
during the simulation. If the system ever reaches a volume outside of the
range provided, the simulation will stop.
@ -71,9 +81,10 @@ With the *analytic* option, the arguments are as follows:
... analytic V_avg N_particles N_coeff Coeff_1 Coeff_2 ... Coeff_N
Note that *V_avg* and *Coeff_i* should all be in the proper units, e.g. if you
are using *units real*, *V_avg* should be in cubic angstroms, and the
coefficients should all be in atmospheres \* cubic angstroms.
Note that *V_avg* and *Coeff_i* should all be in the proper units (e.g., if you
are using *units real*, *V_avg* should be in :math:`\mathrm{\mathring{A}^3}`
and the coefficients should all be in
:math:`\mathrm{atm}\cdot\mathrm{\mathring{A}^3}`\ ).
----------
@ -122,7 +133,7 @@ are written to a file every so often. In order to have LAMMPS report the
modified pressure, you must include the *thermo_modify* command given in
the examples. For the last argument in the command, you should put
XXXX_press, where XXXX is the ID given to the fix bocs command (in the
example, the ID of the fix bocs command is 1 ).
example, the ID of the fix bocs command is 1).
This fix is part of the BOCS package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package <Build_package>` page for more info.
@ -132,7 +143,7 @@ Further information
For more details about the pressure correction and the entire BOCS software
package, visit the `BOCS package on GitHub <bocsgithub_>`_ and read the release
paper by Dunn et. al. :ref:`(Dunn2) <bocs-Dunn2>` .
paper by Dunn et al. :ref:`(Dunn2) <bocs-Dunn2>` .
.. _bocsgithub: https://github.com/noid-group/BOCS

64
doc/src/fix_bond_break.rst
View File

@ -6,7 +6,7 @@ fix bond/break command
Syntax
""""""
.. parsed-literal::
.. code-block:: LAMMPS
fix ID group-ID bond/break Nevery bondtype Rmax keyword values ...
@ -15,7 +15,7 @@ Syntax
* Nevery = attempt bond breaking every this many steps
* bondtype = type of bonds to break
* Rmax = bond longer than Rmax can break (distance units)
* zero or more keyword/value pairs may be appended to args
* zero or more keyword/value pairs may be appended
* keyword = *prob*
.. parsed-literal::
@ -43,42 +43,42 @@ pair of atoms computed by the :doc:`bond_style <bond_style>` command.
Once the bond is broken it will be permanently deleted, as will all
angle, dihedral, and improper interactions that bond is part of.
This is different than a :doc:`pairwise <pair_style>` bond-order
This is different than a :doc:`pair-wise <pair_style>` bond-order
potential such as Tersoff or AIREBO which infers bonds and many-body
interactions based on the current geometry of a small cluster of atoms
and effectively creates and destroys bonds and higher-order many-body
interactions from timestep to timestep as atoms move.
A check for possible bond breakage is performed every *Nevery*
timesteps. If two bonded atoms I,J are further than a distance *Rmax*
of each other, if the bond is of type *bondtype*, and if both I and J
are in the specified fix group, then I,J is labeled as a "possible"
bond to break.
timesteps. If two bonded atoms :math:`i` and :math:`j` are farther than the
distance *Rmax* from each other, the bond is of type *bondtype*, and both
:math:`i` and :math:`j` are in the specified fix group, then the bond between
:math:`i` and :math:`j` is labeled as a "possible" bond to break.
If several bonds involving an atom are stretched, it may have multiple
possible bonds to break. Every atom checks its list of possible bonds
to break and labels the longest such bond as its "sole" bond to break.
After this is done, if atom I is bonded to atom J in its sole bond,
and atom J is bonded to atom I in its sole bond, then the I,J bond is
"eligible" to be broken.
After this is done, if atom :math:`i` is bonded to atom :math:`j` in its sole
bond, and atom :math:`j` is bonded to atom :math:`j` in its sole bond, then the
bond between :math:`i` and :math:`j` is "eligible" to be broken.
Note that these rules mean an atom will only be part of at most one
broken bond on a given timestep. It also means that if atom I chooses
atom J as its sole partner, but atom J chooses atom K is its sole
partner (due to Rjk > Rij), then this means atom I will not be part of
a broken bond on this timestep, even if it has other possible bond
partners.
broken bond on a given time step. It also means that if atom :math:`i` chooses
atom :math:`j` as its sole partner, but atom :math:`j` chooses atom :math:`k`
as its sole partner (because :math:`R_{jk} > R_{ij}`), then this means atom
:math:`i` will not be part of a broken bond on this time step, even if it has
other possible bond partners.
The *prob* keyword can effect whether an eligible bond is actually
broken. The *fraction* setting must be a value between 0.0 and 1.0.
A uniform random number between 0.0 and 1.0 is generated and the
eligible bond is only broken if the random number < fraction.
eligible bond is only broken if the random number is less than *fraction*.
When a bond is broken, data structures within LAMMPS that store bond
topology are updated to reflect the breakage. Likewise, if the bond
topologies are updated to reflect the breakage. Likewise, if the bond
is part of a 3-body (angle) or 4-body (dihedral, improper)
interaction, that interaction is removed as well. These changes
typically affect pairwise interactions between atoms that used to be
typically affect pair-wise interactions between atoms that used to be
part of bonds, angles, etc.
.. note::
@ -88,17 +88,17 @@ part of bonds, angles, etc.
becomes two molecules due to the broken bond, all atoms in both new
molecules retain their original molecule IDs.
Computationally, each timestep this fix operates, it loops over all
Computationally, each time step this fix is invoked, it loops over all
the bonds in the system and computes distances between pairs of bonded
atoms. It also communicates between neighboring processors to
coordinate which bonds are broken. Moreover, if any bonds are broken,
neighbor lists must be immediately updated on the same timestep. This
is to insure that any pairwise interactions that should be turned "on"
neighbor lists must be immediately updated on the same time step. This
is to ensure that any pair-wise interactions that should be turned "on"
due to a bond breaking, because they are no longer excluded by the
presence of the bond and the settings of the
:doc:`special_bonds <special_bonds>` command, will be immediately
recognized. All of these operations increase the cost of a timestep.
Thus you should be cautious about invoking this fix too frequently.
recognized. All of these operations increase the cost of a time step.
Thus, you should be cautious about invoking this fix too frequently.
You can dump out snapshots of the current bond topology via the :doc:`dump local <dump>` command.
@ -107,11 +107,11 @@ You can dump out snapshots of the current bond topology via the :doc:`dump local
Breaking a bond typically alters the energy of a system. You
should be careful not to choose bond breaking criteria that induce a
dramatic change in energy. For example, if you define a very stiff
harmonic bond and break it when 2 atoms are separated by a distance
far from the equilibrium bond length, then the 2 atoms will be
harmonic bond and break it when two atoms are separated by a distance
far from the equilibrium bond length, then the two atoms will be
dramatically released when the bond is broken. More generally, you
may need to thermostat your system to compensate for energy changes
resulting from broken bonds (and angles, dihedrals, impropers).
resulting from broken bonds (as well as angles, dihedrals, and impropers).
See the :doc:`Howto <Howto_broken_bonds>` page on broken bonds for more
information on related features in LAMMPS.
@ -124,14 +124,14 @@ Restart, fix_modify, output, run start/stop, minimize info
No information about this fix is written to :doc:`binary restart files <restart>`. None of the :doc:`fix_modify <fix_modify>` options
are relevant to this fix.
This fix computes two statistics which it stores in a global vector of
length 2, which can be accessed by various :doc:`output commands <Howto_output>`. The vector values calculated by this fix
are "intensive".
This fix computes two statistics, which it stores in a global vector of
length 2. This vector can be accessed by various :doc:`output commands
<Howto_output>`. The vector values calculated by this fix are "intensive".
These are the 2 quantities:
The two quantities in the global vector are
* (1) # of bonds broken on the most recent breakage timestep
* (2) cumulative # of bonds broken
(1) number of bonds broken on the most recent breakage time step
(2) cumulative number of bonds broken
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>`.

126
doc/src/fix_bond_create.rst
View File

@ -10,7 +10,7 @@ fix bond/create/angle command
Syntax
""""""
.. parsed-literal::
.. code-block:: LAMMPS
fix ID group-ID bond/create Nevery itype jtype Rmin bondtype keyword values ...
@ -58,83 +58,84 @@ Description
"""""""""""
Create bonds between pairs of atoms as a simulation runs according to
specified criteria. This can be used to model cross-linking of
specified criteria. This can be used to model the cross-linking of
polymers, the formation of a percolation network, etc. In this
context, a bond means an interaction between a pair of atoms computed
by the :doc:`bond_style <bond_style>` command. Once the bond is created
it will be permanently in place. Optionally, the creation of a bond
can also create angle, dihedral, and improper interactions that bond
can also create angle, dihedral, and improper interactions that the bond
is part of. See the discussion of the *atype*, *dtype*, and *itype*
keywords below.
This is different than a :doc:`pairwise <pair_style>` bond-order
potential such as Tersoff or AIREBO which infers bonds and many-body
This process is different than a :doc:`pair-wise <pair_style>` bond-order
potential such as Tersoff or AIREBO, which infer bonds and many-body
interactions based on the current geometry of a small cluster of atoms
and effectively creates and destroys bonds and higher-order many-body
interactions from timestep to timestep as atoms move.
and effectively create and destroy bonds and higher-order many-body
interactions from time step to time step as the atoms move.
A check for possible new bonds is performed every *Nevery* timesteps.
If two atoms I,J are within a distance *Rmin* of each other, if I is
of atom type *itype*, if J is of atom type *jtype*, if both I and J
are in the specified fix group, if a bond does not already exist
between I and J, and if both I and J meet their respective *maxbond*
requirement (explained below), then I,J is labeled as a "possible"
bond pair.
A check for possible new bonds is performed every *Nevery* time steps.
If two atoms :math:`i` and :math:`j` are within a distance *Rmin* of each
other, atom :math:`i` is of type *itype*, atom :math:`j` is of type *jtype*,
and both :math:`i` and :math:`j` are in the specified fix group, then if a bond
does not already exist between atoms :math:`i` and :math:`j`, and if both
:math:`i` and :math:`j` meet their respective *maxbond* requirements (explained
below), then :math:`i` and :math:`j` are labeled as a "possible" bond pair.
If several atoms are close to an atom, it may have multiple possible
bond partners. Every atom checks its list of possible bond partners
and labels the closest such partner as its "sole" bond partner. After
this is done, if atom I has atom J as its sole partner, and atom J has
atom I as its sole partner, then the I,J bond is "eligible" to be
formed.
this is done, if atom :math:`i` has atom :math:`j` as its sole partner and
atom :math:`j` has atom :math:`i` as its sole partner, then the
:math:`i,j` bond is "eligible" to be formed.
Note that these rules mean an atom will only be part of at most one
created bond on a given timestep. It also means that if atom I
chooses atom J as its sole partner, but atom J chooses atom K is its
sole partner (due to Rjk < Rij), then this means atom I will not form
a bond on this timestep, even if it has other possible bond partners.
Note that these rules mean that an atom will only be part of at most one
created bond on a given time step. It also means that if atom :math:`i`
chooses atom :math:`j` as its sole partner, but atom :math:`j` chooses atom
:math:`k` as its sole partner (because :math:`R_{jk} < R_{ij}`), then atom
:math:`i` will not form a bond on this time step, even if it has other possible
bond partners.
It is permissible to have *itype* = *jtype*\ . *Rmin* must be <= the
pairwise cutoff distance between *itype* and *jtype* atoms, as defined
It is permissible to have *itype* = *jtype*\ . *Rmin* must be :math:`\leq` the
pair-wise cutoff distance between *itype* and *jtype* atoms, as defined
by the :doc:`pair_style <pair_style>` command.
The *iparam* and *jparam* keywords can be used to limit the bonding
functionality of the participating atoms. Each atom keeps track of
how many bonds of *bondtype* it already has. If atom I of
itype already has *maxbond* bonds (as set by the *iparam*
keyword), then it will not form any more. Likewise for atom J. If
*maxbond* is set to 0, then there is no limit on the number of bonds
how many bonds of *bondtype* it already has. If atom :math:`i` of type
*itype* already has *maxbond* bonds (as set by the *iparam*
keyword), then it will not form any more, and likewise for atom :math:`j`.
If *maxbond* is set to 0, then there is no limit on the number of bonds
that can be formed with that atom.
The *newtype* value for *iparam* and *jparam* can be used to change
the atom type of atom I or J when it reaches *maxbond* number of bonds
of type *bondtype*\ . This means it can now interact in a pairwise
the atom type of atom :math:`i` or :math:`j` when it reaches *maxbond* number
of bonds of type *bondtype*\ . This means it can now interact in a pair-wise
fashion with other atoms in a different way by specifying different
:doc:`pair_coeff <pair_coeff>` coefficients. If you do not wish the
atom type to change, simply specify *newtype* as *itype* or *jtype*\ .
The *prob* keyword can also effect whether an eligible bond is
The *prob* keyword can also affect whether an eligible bond is
actually created. The *fraction* setting must be a value between 0.0
and 1.0. A uniform random number between 0.0 and 1.0 is generated and
the eligible bond is only created if the random number < fraction.
the eligible bond is only created if the random number is less than *fraction*.
The *aconstrain* keyword is only available with the fix
bond/create/angle command. It allows to specify a minimal and maximal
angle *amin* and *amax* between the two prospective bonding partners and
a third particle that is already bonded to one of the two partners.
Such a criterion can be important when new angles are defined together
with the formation of a new bond. Without a restriction on the
bond/create/angle command. It allows one to specify minimum and maximum
angles *amin* and *amax*, respectively, between the two prospective bonding
partners and a third particle that is already bonded to one of the two
partners. Such a criterion can be important when new angles are defined
together with the formation of a new bond. Without a restriction on the
permissible angle, and for stiffer angle potentials, very large energies
can arise and lead to uncontrolled behavior.
can arise and lead to unphysical behavior.
Any bond that is created is assigned a bond type of *bondtype*.
When a bond is created, data structures within LAMMPS that store bond
topology are updated to reflect the creation. If the bond is part of
topologies are updated to reflect the creation. If the bond is part of
new 3-body (angle) or 4-body (dihedral, improper) interactions, you
can choose to create new angles, dihedrals, impropers as well, using
can choose to create new angles, dihedrals, and impropers as well using
the *atype*, *dtype*, and *itype* keywords. All of these changes
typically affect pairwise interactions between atoms that are now part
typically affect pair-wise interactions between atoms that are now part
of new bonds, angles, etc.
.. note::
@ -165,19 +166,19 @@ of type *angletype*, with parameters assigned by the corresponding
when bonds are created. See the :doc:`read_data <read_data>` or
:doc:`create_box <create_box>` command for more details. Note that a
data file with no atoms can be used if you wish to add non-bonded
atoms via the :doc:`create atoms <create_atoms>` command, e.g. for a
percolation simulation.
atoms via the :doc:`create atoms <create_atoms>` command (e.g., for a
percolation simulation).
.. note::
LAMMPS stores and maintains a data structure with a list of the
first, second, and third neighbors of each atom (within the bond topology of
the system) for use in weighting pairwise interactions for bonded
the system) for use in weighting pair-wise interactions for bonded
atoms. Note that adding a single bond always adds a new first neighbor
but may also induce \*many\* new second and third neighbors, depending on the
but may also induce **many** new second and third neighbors, depending on the
molecular topology of your system. The "extra special per atom"
parameter must typically be set to allow for the new maximum total
size (first + second + third neighbors) of this per-atom list. There are 2
size (first + second + third neighbors) of this per-atom list. There are two
ways to do this. See the :doc:`read_data <read_data>` or
:doc:`create_box <create_box>` commands for details.
@ -186,15 +187,16 @@ of type *angletype*, with parameters assigned by the corresponding
Even if you do not use the *atype*, *dtype*, or *itype*
keywords, the list of topological neighbors is updated for atoms
affected by the new bond. This in turn affects which neighbors are
considered for pairwise interactions, using the weighting rules set by
considered for pair-wise interactions, using the weighting rules set by
the :doc:`special_bonds <special_bonds>` command. Consider a new bond
created between atoms I,J. If J has a bonded neighbor K, then K
becomes a second neighbor of I. Even if the *atype* keyword is not used
to create angle I-J-K, the pairwise interaction between I and K will
be potentially turned off or weighted by the 1-3 weighting specified
created between atoms :math:`i` and :math:`j`. If :math:`j` has a bonded
neighbor :math:`k`, then :math:`k` becomes a second neighbor of :math:`i`.
Even if the *atype* keyword is not used to create angle :math:`\angle ijk`,
the pair-wise interaction between :math:`i` and :math:`k` could potentially
be turned off or weighted by the 1--3 weighting specified
by the :doc:`special_bonds <special_bonds>` command. This is the case
even if the "angle yes" option was used with that command. The same
is true for third neighbors (1-4 interactions), the *dtype* keyword, and
is true for third neighbors (1--4 interactions), the *dtype* keyword, and
the "dihedral yes" option used with the
:doc:`special_bonds <special_bonds>` command.
@ -203,20 +205,20 @@ define a :doc:`bond_style <bond_style>` and use the
:doc:`bond_coeff <bond_coeff>` command to specify coefficients for the
*bondtype*\ . Similarly, if new atom types are specified by the
*iparam* or *jparam* keywords, they must be within the range of atom
types allowed by the simulation and pairwise coefficients must be
types allowed by the simulation and pair-wise coefficients must be
specified for the new types.
Computationally, each timestep this fix operates, it loops over
Computationally, each time step this fix is invoked, it loops over
neighbor lists and computes distances between pairs of atoms in the
list. It also communicates between neighboring processors to
coordinate which bonds are created. Moreover, if any bonds are
created, neighbor lists must be immediately updated on the same
timestep. This is to insure that any pairwise interactions that
time step. This is to ensure that any pair-wise interactions that
should be turned "off" due to a bond creation, because they are now
excluded by the presence of the bond and the settings of the
:doc:`special_bonds <special_bonds>` command, will be immediately
recognized. All of these operations increase the cost of a timestep.
Thus you should be cautious about invoking this fix too frequently.
recognized. All of these operations increase the cost of a time step.
Thus, you should be cautious about invoking this fix too frequently.
You can dump out snapshots of the current bond topology via the :doc:`dump local <dump>` command.
@ -225,8 +227,8 @@ You can dump out snapshots of the current bond topology via the :doc:`dump local
Creating a bond typically alters the energy of a system. You
should be careful not to choose bond creation criteria that induce a
dramatic change in energy. For example, if you define a very stiff
harmonic bond and create it when 2 atoms are separated by a distance
far from the equilibrium bond length, then the 2 atoms will oscillate
harmonic bond and create it when two atoms are separated by a distance
far from the equilibrium bond length, then the two atoms will oscillate
dramatically when the bond is formed. More generally, you may need to
thermostat your system to compensate for energy changes resulting from
created bonds (and angles, dihedrals, impropers).
@ -245,10 +247,10 @@ length 2, which can be accessed by various :doc:`output commands
<Howto_output>`. The vector values calculated by this fix are
"intensive".
These are the 2 quantities:
The two quantities in the global vector are
* (1) # of bonds created on the most recent creation timestep
* (2) cumulative # of bonds created
(1) number of bonds created on the most recent creation time step
(2) cumulative number of bonds created
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>`.

286
doc/src/fix_bond_react.rst
View File

@ -6,12 +6,12 @@ fix bond/react command
Syntax
""""""
.. parsed-literal::
.. code-block:: LAMMPS
fix ID group-ID bond/react common_keyword values ...
react react-ID react-group-ID Nevery Rmin Rmax template-ID(pre-reacted) template-ID(post-reacted) map_file individual_keyword values ...
react react-ID react-group-ID Nevery Rmin Rmax template-ID(pre-reacted) template-ID(post-reacted) map_file individual_keyword values ...
react react-ID react-group-ID Nevery Rmin Rmax template-ID(pre-reacted) template-ID(post-reacted) map_file individual_keyword values ...
fix ID group-ID bond/react common_keyword values &
react react-ID react-group-ID Nevery Rmin Rmax template-ID(pre-reacted) template-ID(post-reacted) map_file individual_keyword values &
react react-ID react-group-ID Nevery Rmin Rmax template-ID(pre-reacted) template-ID(post-reacted) map_file individual_keyword values &
react react-ID react-group-ID Nevery Rmin Rmax template-ID(pre-reacted) template-ID(post-reacted) map_file individual_keyword values &
...
* ID, group-ID are documented in :doc:`fix <fix>` command.
@ -22,11 +22,12 @@ Syntax
.. parsed-literal::
*stabilization* values = *no* or *yes* *group-ID* *xmax*
*no* = no reaction site stabilization (default)
*yes* = perform reaction site stabilization
*group-ID* = user-assigned prefix for the dynamic group of atoms not currently involved in a reaction
*xmax* = xmax value that is used by an internally-created :doc:`nve/limit <fix_nve_limit>` integrator
*stabilization* values = stabilize group_prefix xmax
stabilize = *yes* or *no*
*yes* = perform reaction site stabilization
*no* = no reaction site stabilization (default)
group_prefix = user-assigned prefix for the dynamic group of atoms not currently involved in a reaction
xmax = value that is used by an internally-created :doc:`nve/limit <fix_nve_limit>` integrator
*reset_mol_ids* values = *yes* or *no*
*yes* = update molecule IDs based on new global topology (default)
*no* = do not update molecule IDs
@ -51,18 +52,18 @@ Syntax
*max_rxn* value = N
N = maximum number of reactions allowed to occur
*stabilize_steps* value = timesteps
timesteps = number of timesteps to apply the internally-created :doc:`nve/limit <fix_nve_limit>` fix to reacting atoms
*custom_charges* value = *no* or *fragmentID*
no = update all atomic charges (default)
fragmentID = ID of molecule fragment whose charges are updated
timesteps = number of time steps to apply the internally-created :doc:`nve/limit <fix_nve_limit>` fix to reacting atoms
*custom_charges* value = *no* or fragment-ID
*no* = update all atomic charges (default)
fragment-ID = ID of molecule fragment whose charges are updated
*molecule* value = *off* or *inter* or *intra*
off = allow both inter- and intramolecular reactions (default)
inter = search for reactions between molecules with different IDs
intra = search for reactions within the same molecule
*modify_create* keyword values
*fit* value = *all* or *fragmentID*
all = use all eligible atoms for create-atoms fit (default)
fragmentID = ID of molecule fragment used for create-atoms fit
*off* = allow both inter- and intramolecular reactions (default)
*inter* = search for reactions between molecules with different IDs
*intra* = search for reactions within the same molecule
*modify_create* values = keyword arg
*fit* arg = *all* or fragment-ID
*all* = use all eligible atoms for create-atoms fit (default)
fragment-ID = ID of molecule fragment used for create-atoms fit
*overlap* value = R
R = only insert atom/molecule if further than R from existing particles (distance units)
@ -99,31 +100,32 @@ other molecules can be identified and deleted. Finally, atoms can be
created and inserted at specific positions relative to the reaction
site.
Fix bond/react does not use quantum mechanical (eg. fix qmmm) or
pairwise bond-order potential (eg. Tersoff or AIREBO) methods to
Fix bond/react does not use quantum mechanical (e.g., :doc:`fix qmmm <fix_qmmm>`) or
pairwise bond-order potential (e.g., :doc:`Tersoff <pair_tersoff>` or
:doc:`AIREBO <pair_airebo>`) methods to
determine bonding changes a priori. Rather, it uses a distance-based
probabilistic criteria to effect predetermined topology changes in
simulations using standard force fields.
This fix was created to facilitate the dynamic creation of polymeric,
amorphous or highly cross-linked systems. A suggested workflow for
using this fix is: 1) identify a reaction to be simulated 2) build a
molecule template of the reaction site before the reaction has
occurred 3) build a molecule template of the reaction site after the
reaction has occurred 4) create a map that relates the
template-atom-IDs of each atom between pre- and post-reaction molecule
templates 5) fill a simulation box with molecules and run a simulation
with fix bond/react.
using this fix is
(1) identify a reaction to be simulated
(2) build a molecule template of the reaction site before the reaction has occurred
(3) build a molecule template of the reaction site after the reaction has occurred
(4) create a map that relates the template-atom-IDs of each atom between pre- and post-reaction molecule templates
(5) fill a simulation box with molecules and run a simulation with fix bond/react.
Only one 'fix bond/react' command can be used at a time. Multiple
reactions can be simultaneously applied by specifying multiple *react*
arguments to a single 'fix bond/react' command. This syntax is
necessary because the 'common keywords' are applied to all reactions.
necessary because the "common" keywords are applied to all reactions.
The *stabilization* keyword enables reaction site stabilization.
Reaction site stabilization is performed by including reacting atoms
in an internally-created fix :doc:`nve/limit <fix_nve_limit>` time
integrator for a set number of timesteps given by the
integrator for a set number of time steps given by the
*stabilize_steps* keyword. While reacting atoms are being time
integrated by the internal nve/limit, they are prevented from being
involved in any new reactions. The *xmax* value keyword should
@ -133,53 +135,54 @@ during the simulation.
Fix bond/react creates and maintains two important dynamic groups of
atoms when using the *stabilization* keyword. The first group contains
all atoms currently involved in a reaction; this group is
automatically thermostatted by an internally-created
automatically time-integrated by an internally-created
:doc:`nve/limit <fix_nve_limit>` integrator. The second group contains
all atoms currently not involved in a reaction. This group should be
used by a thermostat in order to time integrate the system. The name
controlled by a thermostat in order to time integrate the system. The name
of this group of non-reacting atoms is created by appending '_REACT'
to the group-ID argument of the *stabilization* keyword, as shown in
the second example above.
.. note::
When using reaction stabilization, you should generally not have
a separate thermostat which acts on the 'all' group.
When using reaction stabilization, you should generally **not** have
a separate thermostat that acts on the "all" group.
The group-ID set using the *stabilization* keyword can be an existing
static group or a previously-unused group-ID. It cannot be specified
as 'all'. If the group-ID is previously unused, the fix bond/react
as "all". If the group-ID is previously unused, the fix bond/react
command creates a :doc:`dynamic group <group>` that is initialized to
include all atoms. If the group-ID is that of an existing static
group, the group is used as the parent group of new,
internally-created dynamic group. In both cases, this new dynamic
group is named by appending '_REACT' to the group-ID, e.g.
nvt_grp_REACT. By specifying an existing group, you may thermostat
group is named by appending '_REACT' to the group-ID (e.g.,
nvt_grp_REACT). By specifying an existing group, you may thermostat
constant-topology parts of your system separately. The dynamic group
contains only atoms not involved in a reaction at a given timestep,
contains only atoms not involved in a reaction at a given time step,
and therefore should be used by a subsequent system-wide time
integrator such as nvt, npt, or nve, as shown in the second example
above (full examples can be found at examples/PACKAGES/reaction). The time
integrator such as :doc:`fix nvt <fix_nh>`, :doc:`fix npt <fix_nh>`, or
:doc:`fix nve <fix_nve>`, as shown in the second example
above (full examples can be found in examples/PACKAGES/reaction). The time
integration command should be placed after the fix bond/react command
due to the internal dynamic grouping performed by fix bond/react.
.. note::
If the group-ID is an existing static group, react-group-IDs
should also be specified as this static group, or a subset.
should also be specified as this static group or a subset.
The *reset_mol_ids* keyword invokes the :doc:`reset_mol_ids <reset_mol_ids>`
command after a reaction occurs, to ensure that molecule IDs are
consistent with the new bond topology. The group-ID used for
:doc:`reset_mol_ids <reset_mol_ids>` is the group-ID for this fix.
Resetting molecule IDs is necessarily a global operation, and so can
Resetting molecule IDs is necessarily a global operation, so it can
be slow for very large systems.
The following comments pertain to each *react* argument (in other
words, can be customized for each reaction, or reaction step):
words, they can be customized for each reaction, or reaction step):
A check for possible new reaction sites is performed every *Nevery*
timesteps. *Nevery* can be specified with an equal-style
time steps. *Nevery* can be specified with an equal-style
:doc:`variable <variable>`, whose value is rounded up to the nearest
integer.
@ -194,11 +197,11 @@ reaction site is eligible to be modified to match the post-reaction
template.
An initiator atom pair will be identified if several conditions are
met. First, a pair of atoms I,J within the specified react-group-ID of
type itype and jtype must be separated by a distance between *Rmin*
and *Rmax*\ . *Rmin* and *Rmax* can be specified with equal-style
:doc:`variables <variable>`. For example, these reaction cutoffs can
be a function of the reaction conversion using the following commands:
met. First, a pair of atoms :math:`i` and :math:`j` within the specified
react-group-ID of type *itype* and *jtype* must be separated by a distance
between *Rmin* and *Rmax*\ . *Rmin* and *Rmax* can be specified with
equal-style :doc:`variables <variable>`. For example, these reaction cutoffs
can be functions of the reaction conversion using the following commands:
.. code-block:: LAMMPS
@ -207,23 +210,28 @@ be a function of the reaction conversion using the following commands:
variable rmax equal 3+f_myrxn[1]/100 # arbitrary function of reaction count
The following criteria are used if multiple candidate initiator atom
pairs are identified within the cutoff distance: 1) If the initiator
atoms in the pre-reaction template are not 1-2 neighbors (i.e. not
directly bonded) the closest potential partner is chosen. 2)
Otherwise, if the initiator atoms in the pre-reaction template are 1-2
neighbors (i.e. directly bonded) the farthest potential partner is
chosen. 3) Then, if both an atom I and atom J have each other as their
initiator partners, these two atoms are identified as the initiator
atom pair of the reaction site. Note that it can be helpful to select
pairs are identified within the cutoff distance:
(1) If the initiator atoms in the pre-reaction template are not 1--2
neighbors (i.e., not directly bonded) the closest potential partner is
chosen.
(2) Otherwise, if the initiator atoms in the pre-reaction template are 1--2
neighbors (i.e. directly bonded) the farthest potential partner is
chosen.
(3) Then, if both an atom :math:`i` and atom :math:`j` have each other as
initiator partners, these two atoms are identified as the initiator atom
pair of the reaction site.
Note that it can be helpful to select
unique atom types for the initiator atoms: if an initiator atom pair
is identified, as described in the previous steps, but does not
is identified, as described in the previous steps, but it does not
correspond to the same pair specified in the pre-reaction template, an
otherwise eligible reaction could be prevented from occurring. Once
this unique initiator atom pair is identified for each reaction, there
could be two or more reactions that involve the same atom on the same
timestep. If this is the case, only one such reaction is permitted to
time step. If this is the case, only one such reaction is permitted to
occur. This reaction is chosen randomly from all potential reactions
involving the overlapping atom. This capability allows e.g. for
involving the overlapping atom. This capability allows, for example,
different reaction pathways to proceed from identical reaction sites
with user-specified probabilities.
@ -247,19 +255,19 @@ pre-reaction template atoms should be linked to an initiator atom, via
at least one path that does not involve edge atoms. When the
pre-reaction template contains edge atoms, not all atoms, bonds,
charges, etc. specified in the reaction templates will be updated.
Specifically, topology that involves only atoms that are 'too near' to
template edges will not be updated. The definition of 'too near the
edge' depends on which interactions are defined in the simulation. If
Specifically, topology that involves only atoms that are "too near" to
template edges will not be updated. The definition of "too near the
edge" depends on which interactions are defined in the simulation. If
the simulation has defined dihedrals, atoms within two bonds of edge
atoms are considered 'too near the edge.' If the simulation defines
atoms are considered "too near the edge." If the simulation defines
angles, but not dihedrals, atoms within one bond of edge atoms are
considered 'too near the edge.' If just bonds are defined, only edge
atoms are considered 'too near the edge.'
considered "too near the edge." If just bonds are defined, only edge
atoms are considered "too near the edge."
.. note::
Small molecules, i.e. ones that have all their atoms contained
within the reaction templates, never have edge atoms.
Small molecules (i.e., ones that have all their atoms contained
within the reaction templates) never have edge atoms.
Note that some care must be taken when a building a molecule template
for a given simulation. All atom types in the pre-reacted template
@ -282,7 +290,7 @@ provided on the :doc:`molecule <molecule>` command page.
.. note::
When a reaction occurs, it is possible that the resulting
topology/atom (e.g. special bonds, dihedrals, etc.) exceeds that of
topology/atom (e.g., special bonds, dihedrals) exceeds that of
the existing system and reaction templates. As when inserting
molecules, enough space for this increased topology/atom must be
reserved by using the relevant "extra" keywords to the
@ -292,14 +300,14 @@ The map file is a text document with the following format:
A map file has a header and a body. The header of map file the
contains one mandatory keyword and five optional keywords. The
mandatory keyword is 'equivalences':
mandatory keyword is *equivalences*\ :
.. parsed-literal::
N *equivalences* = # of atoms N in the reaction molecule templates
The optional keywords are 'edgeIDs', 'deleteIDs', 'chiralIDs' and
'constraints':
The optional keywords are *edgeIDs*\ , *deleteIDs*\ , *chiralIDs*\ , and
*constraints*\ :
.. parsed-literal::
@ -311,25 +319,25 @@ The optional keywords are 'edgeIDs', 'deleteIDs', 'chiralIDs' and
The body of the map file contains two mandatory sections and five
optional sections. The first mandatory section begins with the keyword
'InitiatorIDs' and lists the two atom IDs of the initiator atom pair
"InitiatorIDs" and lists the two atom IDs of the initiator atom pair
in the pre-reacted molecule template. The second mandatory section
begins with the keyword 'Equivalences' and lists a one-to-one
begins with the keyword "Equivalences" and lists a one-to-one
correspondence between atom IDs of the pre- and post-reacted
templates. The first column is an atom ID of the pre-reacted molecule
template, and the second column is the corresponding atom ID of the
post-reacted molecule template. The first optional section begins with
the keyword 'EdgeIDs' and lists the atom IDs of edge atoms in the
the keyword "EdgeIDs" and lists the atom IDs of edge atoms in the
pre-reacted molecule template. The second optional section begins with
the keyword 'DeleteIDs' and lists the atom IDs of pre-reaction
the keyword "DeleteIDs" and lists the atom IDs of pre-reaction
template atoms to delete. The third optional section begins with the
keyword 'CreateIDs' and lists the atom IDs of the post-reaction
keyword "CreateIDs" and lists the atom IDs of the post-reaction
template atoms to create. The fourth optional section begins with the
keyword 'ChiralIDs' lists the atom IDs of chiral atoms whose
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
the keyword "Constraints" and lists additional criteria that must be
satisfied in order for the reaction to occur. Currently, there are
six types of constraints available, as discussed below: 'distance',
'angle', 'dihedral', 'arrhenius', 'rmsd', and 'custom'.
six types of constraints available, as discussed below: "distance",
"angle", "dihedral", "arrhenius", "rmsd", and "custom".
A sample map file is given below:
@ -384,18 +392,24 @@ two sub-keywords, *fit* and *overlap*. One or more of the sub-keywords
may be used after the *modify_create* keyword. The *fit* sub-keyword
can be used to specify which post-reaction atoms are used for the
optimal translation and rotation of the post-reaction template. The
*fragmentID* value of the *fit* sub-keyword must be the name of a
fragment-ID value of the *fit* sub-keyword must be the name of a
molecule fragment defined in the post-reaction :doc:`molecule
<molecule>` template, and only atoms in this fragment are used for the
fit. Atoms are created only if no current atom in the simulation is
within a distance R of any created atom, including the effect of
periodic boundary conditions if applicable. R is defined by the
*overlap* sub-keyword. Note that the default value for R is 0.0, which
within a distance :math:`R` of any created atom, including the effect of
periodic boundary conditions if applicable. :math:`R` is defined by the
*overlap* sub-keyword. Note that the default value for :math:`R` is 0.0, which
will allow atoms to strongly overlap if you are inserting where other
atoms are present. The velocity of each created atom is initialized in
a random direction with a magnitude calculated from the instantaneous
temperature of the reaction site.
.. note::
The 'Coords' section must be included in the post-reaction template
when creating atoms because these coordinates are used to determine
where new atoms are inserted.
The handedness of atoms that are chiral centers can be enforced by
listing their IDs in the ChiralIDs section. A chiral atom must be
bonded to four atoms with mutually different atom types. This feature
@ -406,40 +420,40 @@ and the relative position of the fourth bonded atom determines the
chiral center's handedness.
Any number of additional constraints may be specified in the
Constraints section of the map file. The constraint of type 'distance'
Constraints section of the map file. The constraint of type "distance"
has syntax as follows:
.. parsed-literal::
distance *ID1* *ID2* *rmin* *rmax*
where 'distance' is the required keyword, *ID1* and *ID2* are
where "distance" is the required keyword, *ID1* and *ID2* are
pre-reaction atom IDs (or molecule-fragment IDs, see below), and these
two atoms must be separated by a distance between *rmin* and *rmax*
for the reaction to occur.
The constraint of type 'angle' has the following syntax:
The constraint of type "angle" has the following syntax:
.. parsed-literal::
angle *ID1* *ID2* *ID3* *amin* *amax*
where 'angle' is the required keyword, *ID1*, *ID2* and *ID3* are
where "angle" is the required keyword, *ID1*, *ID2* and *ID3* are
pre-reaction atom IDs (or molecule-fragment IDs, see below), and these
three atoms must form an angle between *amin* and *amax* for the
reaction to occur (where *ID2* is the central atom). Angles must be
specified in degrees. This constraint can be used to enforce a certain
orientation between reacting molecules.
The constraint of type 'dihedral' has the following syntax:
The constraint of type "dihedral" has the following syntax:
.. parsed-literal::
dihedral *ID1* *ID2* *ID3* *ID4* *amin* *amax* *amin2* *amax2*
where 'dihedral' is the required keyword, and *ID1*, *ID2*, *ID3*
where "dihedral" is the required keyword, and *ID1*, *ID2*, *ID3*
and *ID4* are pre-reaction atom IDs (or molecule-fragment IDs, see
below). Dihedral angles are calculated in the interval (-180,180].
below). Dihedral angles are calculated in the interval :math:`(-180^\circ,180^\circ]`.
Refer to the :doc:`dihedral style <dihedral_style>` documentation for
further details on convention. If *amin* is less than *amax*, these
four atoms must form a dihedral angle greater than *amin* **and** less
@ -447,7 +461,7 @@ than *amax* for the reaction to occur. If *amin* is greater than
*amax*, these four atoms must form a dihedral angle greater than
*amin* **or** less than *amax* for the reaction to occur. Angles must
be specified in degrees. Optionally, a second range of permissible
angles *amin2*-*amax2* can be specified.
angles *amin2* to *amax2* can be specified.
For the 'distance', 'angle', and 'dihedral' constraints (explained
above), atom IDs can be replaced by pre-reaction molecule-fragment
@ -457,11 +471,11 @@ fragment. The molecule fragment must have been defined in the
:doc:`molecule <molecule>` command for the pre-reaction template.
The constraint of type 'arrhenius' imposes an additional reaction
probability according to the temperature-dependent Arrhenius equation:
probability according to the modified Arrhenius equation,
.. math::
k = AT^{n}e^{\frac{-E_{a}}{k_{B}T}}
k = AT^{n}e^{-E_{a}/k_{B}T}.
The Arrhenius constraint has the following syntax:
@ -469,11 +483,11 @@ The Arrhenius constraint has the following syntax:
arrhenius *A* *n* *E_a* *seed*
where 'arrhenius' is the required keyword, *A* is the pre-exponential
where "arrhenius" is the required keyword, *A* is the pre-exponential
factor, *n* is the exponent of the temperature dependence, :math:`E_a`
is the activation energy (:doc:`units <units>` of energy), and *seed* is a
random number seed. The temperature is defined as the instantaneous
temperature averaged over all atoms in the reaction site, and is
temperature averaged over all atoms in the reaction site and is
calculated in the same manner as for example
:doc:`compute temp/chunk <compute_temp_chunk>`. Currently, there are no
options for additional temperature averaging or velocity-biased
@ -487,7 +501,7 @@ The constraint of type 'rmsd' has the following syntax:
rmsd *RMSDmax* *molfragment*
where 'rmsd' is the required keyword, and *RMSDmax* is the maximum
where "rmsd" is the required keyword, and *RMSDmax* is the maximum
root-mean-square deviation between atom positions of the pre-reaction
template and the local reaction site (distance units), after optimal
translation and rotation of the pre-reaction template. Optionally, the
@ -500,26 +514,26 @@ 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:
The constraint of type "custom" has the following syntax:
.. parsed-literal::
custom *varstring*
where 'custom' is the required keyword, and *varstring* is a
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
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
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:
@ -535,8 +549,8 @@ reaction can be imposed as follows:
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'
occurring by using an inequality and the :doc:`random(x,y,z) <variable>`
function available for equal-style variables, similar to the 'arrhenius'
constraint above.
By default, all constraints must be satisfied for the reaction to
@ -561,40 +575,42 @@ within LAMMPS that store bond topology are updated to reflect the
post-reacted molecule template. All force fields with fixed bonds,
angles, dihedrals or impropers are supported.
A few capabilities to note: 1) You may specify as many *react*
arguments as desired. For example, you could break down a complicated
reaction mechanism into several reaction steps, each defined by its
own *react* argument. 2) While typically a bond is formed or removed
between the initiator atoms specified in the pre-reacted molecule
template, this is not required. 3) By reversing the order of the pre-
and post- reacted molecule templates in another *react* argument, you
can allow for the possibility of one or more reverse reactions.
A few capabilities to note:
(1) You may specify as many *react* arguments as desired. For example, you
could break down a complicated reaction mechanism into several reaction
steps, each defined by its own *react* argument.
(2) While typically a bond is formed or removed between the initiator atoms
specified in the pre-reacted molecule template, this is not required.
(3) By reversing the order of the pre- and post-reacted molecule templates in
another *react* argument, you can allow for the possibility of one or
more reverse reactions.
The optional keywords deal with the probability of a given reaction
occurring as well as the stable equilibration of each reaction site as
it occurs:
it occurs.
The *prob* keyword can affect whether or not an eligible reaction
actually occurs. The fraction setting must be a value between 0.0 and
1.0, and can be specified with an equal-style :doc:`variable <variable>`.
A uniform random number between 0.0 and 1.0 is generated and the
eligible reaction only occurs if the random number is less than the
fraction. Up to N reactions are permitted to occur, as optionally
fraction. Up to :math:`N` reactions are permitted to occur, as optionally
specified by the *max_rxn* keyword.
The *stabilize_steps* keyword allows for the specification of how many
timesteps a reaction site is stabilized before being returned to the
time steps a reaction site is stabilized before being returned to the
overall system thermostat. In order to produce the most physical
behavior, this 'reaction site equilibration time' should be tuned to
behavior, this "reaction site equilibration time" should be tuned to
be as small as possible while retaining stability for a given system
or reaction step. After a limited number of case studies, this number
has been set to a default of 60 timesteps. Ideally, it should be
has been set to a default of 60 time steps. Ideally, it should be
individually tuned for each fix reaction step. Note that in some
situations, decreasing rather than increasing this parameter will
result in an increase in stability.
The *custom_charges* keyword can be used to specify which atoms'
atomic charges are updated. When the value is set to 'no', all atomic
atomic charges are updated. When the value is set to *no*\ , all atomic
charges are updated to those specified by the post-reaction template
(default). Otherwise, the value should be the name of a molecule
fragment defined in the pre-reaction molecule template. In this case,
@ -602,10 +618,10 @@ only the atomic charges of atoms in the molecule fragment are updated.
The *molecule* keyword can be used to force the reaction to be
intermolecular, intramolecular or either. When the value is set to
'off', molecule IDs are not considered when searching for reactions
(default). When the value is set to 'inter', the initiator atoms must
*off*\ , molecule IDs are not considered when searching for reactions
(default). When the value is set to *inter*\ , the initiator atoms must
have different molecule IDs in order to be considered for the
reaction. When the value is set to 'intra', only initiator atoms with
reaction. When the value is set to *intra*\ , only initiator atoms with
the same molecule ID are considered for the reaction.
A few other considerations:
@ -627,15 +643,15 @@ all currently-reacting atoms:
This command must be added after the fix bond/react command, and
will apply to all reactions.
Computationally, each timestep this fix operates, it loops over
Computationally, each time step this fix is invoked, it loops over
neighbor lists (for bond-forming reactions) and computes distances
between pairs of atoms in the list. It also communicates between
neighboring processors to coordinate which bonds are created and/or
removed. All of these operations increase the cost of a timestep. Thus
removed. All of these operations increase the cost of a time step. Thus,
you should be cautious about invoking this fix too frequently.
You can dump out snapshots of the current bond topology via the dump
local command.
You can dump out snapshots of the current bond topology via the
:doc:`dump local <dump>` command.
----------
@ -649,20 +665,20 @@ allow for smooth restarts. None of the :doc:`fix_modify <fix_modify>`
options are relevant to this fix.
This fix computes one statistic for each *react* argument that it
stores in a global vector, of length 'number of react arguments', that
stores in a global vector, of length (number of react arguments), that
can be accessed by various :doc:`output commands <Howto_output>`. The
vector values calculated by this fix are "intensive".
These is 1 quantity for each react argument:
There is one quantity in the global vector for each *react* argument:
* (1) cumulative # of reactions occurred
(1) cumulative number of reactions that occurred
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>`.
When fix bond/react is 'unfixed', all internally-created groups are
deleted. Therefore, fix bond/react can only be unfixed after unfixing
all other fixes that use any group created by fix bond/react.
When fix bond/react is ":doc:`unfixed <unfix>`", all internally-created
groups are deleted. Therefore, fix bond/react can only be unfixed after
unfixing all other fixes that use any group created by fix bond/react.
Restrictions
""""""""""""
@ -683,7 +699,7 @@ Default
"""""""
The option defaults are stabilization = no, prob = 1.0, stabilize_steps = 60,
reset_mol_ids = yes, custom_charges = no, molecule = off, modify_create = no
reset_mol_ids = yes, custom_charges = no, molecule = off, modify_create = *fit all*
----------

77
doc/src/fix_brownian.rst
View File

@ -14,7 +14,7 @@ fix brownian/asphere command
Syntax
""""""
.. parsed-literal::
.. code-block:: LAMMPS
fix ID group-ID style_name temp seed keyword args
@ -27,23 +27,23 @@ Syntax
.. 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*
*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
*rotation_temp* values = *T* for *brownian/sphere* and *brownian/asphere*
*rotation_temp* values = *T* for *brownian/sphere* and *brownian/asphere*
*T* = rotation temperature, which can be different then *temp* when out of equilibrium
*planar_rotation* values = None (constrains rotational diffusion to be in xy plane if in 3D)
*planar_rotation* values = none (constrains rotational diffusion to be in xy plane if in 3D)
Examples
""""""""
@ -71,9 +71,10 @@ 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,
d\mathbf{r} = \boldsymbol{\gamma}_t^{-1}\mathbf{F}dt
+ \sqrt{2k_B T}\boldsymbol{\gamma}_t^{-1/2}d\mathbf{W}_t,
in the lab-frame (i.e. :math:`\mathbf{\gamma}_t` is not diagonal, but
in the lab-frame (i.e., :math:`\boldsymbol{\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
@ -92,15 +93,15 @@ updated. This style therefore requires the hybrid atom style
.. math::
\mathbf{\mu}(t+dt) = \frac{\mathbf{\mu}(t) + \mathbf{\omega} \times \mathbf{\mu}dt
}{|\mathbf{\mu}(t) + \mathbf{\omega} \times \mathbf{\mu}|}
\boldsymbol{\mu}(t+dt) = \frac{\boldsymbol{\mu}(t) + \boldsymbol{\omega} \times \boldsymbol{\mu}dt
}{|\boldsymbol{\mu}(t) + \boldsymbol{\omega} \times \boldsymbol{\mu}|}
which correctly reproduces a Boltzmann distribution of orientations and
rotational diffusion moments (see :ref:`(Ilie) <Ilie1>`) when
.. math::
\mathbf{\omega} = \frac{\mathbf{T}}{\gamma_r} + \sqrt{\frac{2 k_B T_{rot}}{\gamma_r}\frac{d\mathbf{W}}{dt}},
\boldsymbol{\omega} = \frac{\mathbf{T}}{\gamma_r} + \sqrt{\frac{2 k_B T_{rot}}{\gamma_r}\frac{d\mathbf{W}}{dt}},
with :math:`d\mathbf{W}` being a random number with zero mean and variance :math:`dt`
and :math:`T_{rot}` is *rotation_temp*.
@ -114,19 +115,20 @@ the quaternion
.. math::
\mathbf{q}(t+dt) = \frac{\mathbf{q}(t) + d\mathbf{q}}{|\mathbf{q}(t) + d\mathbf{q}|}
\mathbf{q}(t+dt) = \frac{\mathbf{q}(t) + d\mathbf{q}}{\lVert\mathbf{q}(t) + d\mathbf{q}\rVert}
which correctly reproduces a Boltzmann distribution of orientations and rotational
diffusion moments (see :ref:`(Ilie) <Ilie1>`) when the quaternion step given by
diffusion moments [see :ref:`(Ilie) <Ilie1>`] when the quaternion step is given by
.. math::
d\mathbf{q} = \mathbf{\Psi}\mathbf{\omega}dt
d\mathbf{q} = \boldsymbol{\Psi}\boldsymbol{\omega}dt
where :math:`\mathbf{Psi}` has rows :math:`(-q_1,-q_2,-q_3)`, :math:`(q_0,-q_3,q_2)`,
:math:`(q_3,q_0,-q_1)`, and :math:`(-q_2,q_1,q_0)`. :math:`\mathbf{\omega}` is
evaluated in the body frame of reference where the friction tensor is diagonal.
See :ref:`(Delong) <Delong1>` for more details of a similar algorithm.
where :math:`\boldsymbol{\Psi}` has rows :math:`(-q_1,-q_2,-q_3)`,
:math:`(q_0,-q_3,q_2)`, :math:`(q_3,q_0,-q_1)`, and :math:`(-q_2,q_1,q_0)`.
:math:`\boldsymbol{\omega}` is evaluated in the body frame of reference where the
friction tensor is diagonal. See :ref:`(Delong) <Delong1>` for more details of
a similar algorithm.
---------
@ -136,11 +138,11 @@ See :ref:`(Delong) <Delong1>` for more details of a similar algorithm.
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
between the particles and the surrounding (implicit) solvent. For example,
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)
is the sphere's diameter). A similar (though more complex)
relationship holds for ellipsoids and rod-like particles. The
translational diffusion and rotational diffusion are given by
*temp/gamma_t* and *rotation_temp/gamma_r*.
@ -150,7 +152,7 @@ See :ref:`(Delong) <Delong1>` for more details of a similar algorithm.
.. note::
Temperature computation using the :doc:`compute temp <compute_temp>`
will not correctly compute temperature of these overdamped dynamics
will not correctly compute the 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
@ -165,7 +167,7 @@ is generated from a uniform distribution (see
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
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>`.
@ -184,8 +186,8 @@ 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).
*gamma_r_eigen* must be *inf* (only rotation in *x*\ --\ *y* plane), and the third
value of *gamma_t_eigen* must be *inf* (only diffusion in the *x*\ --\ *y* plane).
If the *dipole* keyword is used, then the dipole moments of the particles
are updated as described above. Only compatible with *brownian/asphere*
@ -196,13 +198,13 @@ will be occur at this prescribed temperature instead of *temp*. Only
compatible with *brownian/sphere* and *brownian/asphere*.
If the *planar_rotation* keyword is used, then rotation is constrained
to the xy plane in a 3D simulation. Only compatible with
to the *x*\ -- *y* plane in a 3D simulation. Only compatible with
*brownian/sphere* and *brownian/asphere* in 3D.
----------
.. note::
For style *brownian/asphere*, the components *gamma_t_eigen* =(x,x,x) and
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.
@ -215,7 +217,6 @@ 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>`.

2
doc/src/fix_colvars.rst
View File

@ -13,7 +13,7 @@ Syntax
* ID, group-ID are documented in :doc:`fix <fix>` command
* colvars = style name of this fix command
* configfile = the configuration file for the colvars module
* keyword = *input* or *output* or *seed* or *tstat*
* keyword = *input* or *output* or *seed* or *unwrap* or *tstat*
.. parsed-literal::

Some files were not shown because too many files have changed in this diff Show More