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

Fix merge conflicts, minor style fixes

Browse Source
This commit is contained in:
Joel Thomas Clemmer
2021-11-01 18:13:06 -06:00
parent 69e600c404 b15c02e3cd
commit d7f7835069
1240 changed files with 46027 additions and 14730 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
doc/src/Build.rst
View File

@ -22,4 +22,5 @@ page.
Build_extras
Build_manual
Build_windows
Build_diskspace
Build_development

16
doc/src/Build_development.rst
View File

@ -56,16 +56,18 @@ Report missing and unneeded '#include' statements (CMake only)
--------------------------------------------------------------
The conventions for how and when to use and order include statements in
LAMMPS are `documented in a separate file <https://github.com/lammps/lammps/blob/master/doc/include-file-conventions.md>`_
(also included in the source code distribution). To assist with following
LAMMPS are documented in :doc:`Modify_style`. To assist with following
these conventions one can use the `Include What You Use tool <https://include-what-you-use.org/>`_.
This is still under development and for large and complex projects like LAMMPS
This tool is still under development and for large and complex projects like LAMMPS
there are some false positives, so suggested changes need to be verified manually.
It is recommended to use at least version 0.14, which has much fewer incorrect
reports than earlier versions.
It is recommended to use at least version 0.16, which has much fewer incorrect
reports than earlier versions. To install the IWYU toolkit, you need to have
the clang compiler **and** its development package installed. Download the IWYU
version that matches the version of the clang compiler, configure, build, and
install it.
The necessary steps to generate the report can be enabled via a
CMake variable:
The necessary steps to generate the report can be enabled via a CMake variable
during CMake configuration.
.. code-block:: bash

45
doc/src/Build_diskspace.rst Normal file
View File

@ -0,0 +1,45 @@
Notes for saving disk space when building LAMMPS from source
------------------------------------------------------------
LAMMPS is a large software project with a large number of source files,
extensive documentation, and a large collection of example files.
When downloading LAMMPS by cloning the
`git repository from GitHub <https://github.com/lammps/lammps>`_ this
will by default also download the entire commit history since September 2006.
Compiling LAMMPS will add the storage requirements of the compiled object
files and libraries to the tally.
In a user account on an HPC cluster with filesystem quotas or in other
environments with restricted disk space capacity it may be needed to
reduce the storage requirements. Here are some suggestions:
- Create a so-called shallow repository by cloning only the last commit
instead of the full project history by using ``git clone git@github.com:lammps/lammps --depth=1 --branch=develop``.
This reduces the downloaded size to about half. With ``--depth=1`` it is not possible to check out different
versions/branches of LAMMPS, using ``--depth=1000`` will make multiple recent versions available at little
extra storage needs (the entire git history had nearly 30,000 commits in fall 2021).
- Download a tar archive from either the `download section on the LAMMPS homepage <https://www.lammps.org/download.html>`_
or from the `LAMMPS releases page on GitHub <https://github.com/lammps/lammps/releases>`_ these will not
contain the git history at all.
- Build LAMMPS without the debug flag (remove ``-g`` from the machine makefile or use ``-DCMAKE_BUILD_TYPE=Release``)
or use the ``strip`` command on the LAMMPS executable when no more debugging would be needed. The strip command
may also be applied to the LAMMPS shared library. The static library may be deleted entirely.
- Delete compiled object files and libraries after copying the LAMMPS executable to a permanent location.
When using the traditional build process, one may use ``make clean-<machine>`` or ``make clean-all``
to delete object files in the src folder. For CMake based builds, one may use ``make clean`` or just
delete the entire build folder.
- The folders containing the documentation tree (doc), the examples (examples) are not needed to build and
run LAMMPS and can be safely deleted. Some files in the potentials folder are large and may be deleted,
if not needed. The largest of those files (occupying about 120 MBytes combined) will only be downloaded on
demand, when the corresponding package is installed.
- When using the CMake build procedure, the compilation can be done on a (local) scratch storage that will not
count toward the quota. A local scratch file system may offer the additional benefit of speeding up creating
object files and linking with libraries compared to a networked file system. Also with CMake (and unlike with
the traditional make) it is possible to compile LAMMPS executables with different settings and packages included
from the same source tree since all the configuration information is stored in the build folder. So it is
not necessary to have multiple copies of LAMMPS.

20
doc/src/Build_manual.rst
View File

@ -22,7 +22,6 @@ files. Here is a list with descriptions:
.gitignore # list of files and folders to be ignored by git
doxygen-warn.log # logfile with warnings from running doxygen
github-development-workflow.md # notes on the LAMMPS development workflow
include-file-conventions.md # notes on LAMMPS' include file conventions
If you downloaded LAMMPS as a tarball from `the LAMMPS website <lws_>`_,
the html folder and the PDF files should be included.
@ -34,12 +33,15 @@ various tools and files. Some of them have to be installed (see below). For
the rest the build process will attempt to download and install them into
a python virtual environment and local folders.
A current version of the manual (latest patch release, aka unstable
branch) is is available online at:
`https://docs.lammps.org/Manual.html <https://docs.lammps.org/Manual.html>`_.
A version of the manual corresponding to the ongoing development (aka master branch)
is available online at: `https://docs.lammps.org/latest/
<https://docs.lammps.org/latest/>`_
A current version of the manual (latest patch release, that is the state
of the *release* branch) is is available online at:
`https://docs.lammps.org/ <https://docs.lammps.org/>`_.
A version of the manual corresponding to the ongoing development (that is
the state of the *develop* branch) is available online at:
`https://docs.lammps.org/latest/ <https://docs.lammps.org/latest/>`_
A version of the manual corresponding to the latest stable LAMMPS release
(that is the state of the *stable* branch) is available online at:
`https://docs.lammps.org/stable/ <https://docs.lammps.org/stable/>`_
Build using GNU make
--------------------
@ -75,8 +77,8 @@ folder. The following ``make`` commands are available:
.. code-block:: bash
make html # generate HTML in html dir using Sphinx
make pdf # generate PDF as Manual.pdf using Sphinx and pdflatex
make fetch # fetch HTML pages and PDF files from LAMMPS web site
make pdf # generate PDF as Manual.pdf using Sphinx and PDFLaTeX
make fetch # fetch HTML pages and PDF files from LAMMPS website
# and unpack into the html_www folder and Manual_www.pdf
make epub # generate LAMMPS.epub in ePUB format using Sphinx
make mobi # generate LAMMPS.mobi in MOBI format using ebook-convert

35
doc/src/Build_settings.rst
View File

@ -71,7 +71,8 @@ LAMMPS can use them if they are available on your system.
-D FFTW3_INCLUDE_DIR=path # path to FFTW3 include files
-D FFTW3_LIBRARY=path # path to FFTW3 libraries
-D FFT_FFTW_THREADS=on # enable using threaded FFTW3 libraries
-D FFTW3_OMP_LIBRARY=path # path to FFTW3 OpenMP wrapper libraries
-D FFT_FFTW_THREADS=on # enable using OpenMP threaded FFTW3 libraries
-D MKL_INCLUDE_DIR=path # ditto for Intel MKL library
-D FFT_MKL_THREADS=on # enable using threaded FFTs with MKL libraries
-D MKL_LIBRARY=path # path to MKL libraries
@ -320,9 +321,7 @@ following settings:
.. code-block:: make
LMP_INC = -DLAMMPS_JPEG
LMP_INC = -DLAMMPS_PNG
LMP_INC = -DLAMMPS_FFMPEG
LMP_INC = -DLAMMPS_JPEG -DLAMMPS_PNG -DLAMMPS_FFMPEG <other LMP_INC settings>
JPG_INC = -I/usr/local/include # path to jpeglib.h, png.h, zlib.h header files if make cannot find them
JPG_PATH = -L/usr/lib # paths to libjpeg.a, libpng.a, libz.a (.so) files if make cannot find them
@ -353,8 +352,10 @@ Read or write compressed files
-----------------------------------------
If this option is enabled, large files can be read or written with
gzip compression by several LAMMPS commands, including
:doc:`read_data <read_data>`, :doc:`rerun <rerun>`, and :doc:`dump <dump>`.
compression by ``gzip`` or similar tools by several LAMMPS commands,
including :doc:`read_data <read_data>`, :doc:`rerun <rerun>`, and
:doc:`dump <dump>`. Currently supported compression tools are:
``gzip``, ``bzip2``, ``zstd``, and ``lzma``.
.. tabs::
@ -363,23 +364,23 @@ gzip compression by several LAMMPS commands, including
.. code-block:: bash
-D WITH_GZIP=value # yes or no
# default is yes if CMake can find gzip, else no
-D GZIP_EXECUTABLE=path # path to gzip executable if CMake cannot find it
# default is yes if CMake can find the gzip program, else no
.. tab:: Traditional make
.. code-block:: make
LMP_INC = -DLAMMPS_GZIP
LMP_INC = -DLAMMPS_GZIP <other LMP_INC settings>
This option requires that your operating system fully supports the "popen()"
function in the standard runtime library and that a ``gzip`` executable can be
found by LAMMPS during a run.
This option requires that your operating system fully supports the
"popen()" function in the standard runtime library and that a ``gzip``
or other executable can be found by LAMMPS in the standard search path
during a run.
.. note::
On some clusters with high-speed networks, using the "fork()" library
call (required by "popen()") can interfere with the fast communication
On clusters with high-speed networks, using the "fork()" library call
(required by "popen()") can interfere with the fast communication
library and lead to simulations using compressed output or input to
hang or crash. For selected operations, compressed file I/O is also
available using a compression library instead, which is what the
@ -451,7 +452,7 @@ those systems:
.. code-block:: make
LMP_INC = -DLAMMPS_LONGLONG_TO_LONG
LMP_INC = -DLAMMPS_LONGLONG_TO_LONG <other LMP_INC settings>
----------
@ -478,7 +479,7 @@ e.g. to Python. Of course, the calling code has to be set up to
.. code-block:: make
LMP_INC = -DLAMMPS_EXCEPTIONS
LMP_INC = -DLAMMPS_EXCEPTIONS <other LMP_INC settings>
.. note::
@ -519,7 +520,7 @@ executable, not the library.
.. code-block:: make
LMP_INC = -DLAMMPS_TRAP_FPE
LMP_INC = -DLAMMPS_TRAP_FPE <other LMP_INC settings>
After compilation with this flag set, the LAMMPS executable will stop
and produce a core dump when a division by zero, overflow, illegal math

44
doc/src/Build_windows.rst
View File

@ -4,6 +4,7 @@ Notes for building LAMMPS on Windows
* :ref:`General remarks <generic>`
* :ref:`Running Linux on Windows <linux>`
* :ref:`Using GNU GCC ported to Windows <gnu>`
* :ref:`Using Visual Studio <msvc>`
* :ref:`Using a cross-compiler <cross>`
----------
@ -31,13 +32,13 @@ pre-compiled Windows binary packages are sufficient for your needs. If
it is necessary for you to compile LAMMPS on a Windows machine
(e.g. because it is your main desktop), please also consider using a
virtual machine software and compile and run LAMMPS in a Linux virtual
machine, or - if you have a sufficiently up-to-date Windows 10
installation - consider using the Windows subsystem for Linux. This
optional Windows feature allows you to run the bash shell from Ubuntu
from within Windows and from there on, you can pretty much use that
shell like you are running on an Ubuntu Linux machine (e.g. installing
software via apt-get and more). For more details on that, please see
:doc:`this tutorial <Howto_wsl>`.
machine, or - if you have a sufficiently up-to-date Windows 10 or
Windows 11 installation - consider using the Windows subsystem for
Linux. This optional Windows feature allows you to run the bash shell
from Ubuntu from within Windows and from there on, you can pretty much
use that shell like you are running on an Ubuntu Linux machine
(e.g. installing software via apt-get and more). For more details on
that, please see :doc:`this tutorial <Howto_wsl>`.
.. _gnu:
@ -67,6 +68,35 @@ requiring changes to the LAMMPS source code, or figure out corrections
yourself, please report them on the lammps-users mailing list, or file
them as an issue or pull request on the LAMMPS GitHub project.
.. _msvc:
Using Microsoft Visual Studio
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Following the integration of the :doc:`platform namespace
<Developer_platform>` into the LAMMPS code base, portability of LAMMPS
to be compiled on Windows using Visual Studio has been significantly
improved. This has been tested with Visual Studio 2019 (aka version
16). Not all features and packages in LAMMPS are currently supported
out of the box, but a preset ``cmake/presets/windows.cmake`` is provided
that contains the packages that have been compiled successfully. You
must use the CMake based build procedure, and either use the integrated
CMake support of Visual Studio or use an external CMake installation to
create build files for the Visual Studio build system. Please note that
on launching Visual Studio it will scan the directory tree and likely
miss the correct master ``CMakeLists.txt``. Try to open the
``cmake/CMakeSettings.json`` and use those CMake configurations as a
starting point. It is also possible to configure and compile LAMMPS
from the command line with a CMake binary from `cmake.org <https://cmake.org>`_.
To support running in parallel you can compile with OpenMP enabled using
the OPENMP package or install Microsoft MPI (including the SDK) and compile
LAMMPS with MPI enabled.
This is work in progress and you should contact the LAMMPS developers
via GitHub, the forum, or the mailing list, if you have questions or
LAMMPS specific problems.
.. _cross:
Using a cross-compiler

3
doc/src/Commands_fix.rst
View File

@ -23,6 +23,7 @@ OPT.
:columns: 5
* :doc:`accelerate/cos <fix_accelerate_cos>`
* :doc:`acks2/reaxff (k) <fix_acks2_reaxff>`
* :doc:`adapt <fix_adapt>`
* :doc:`adapt/fep <fix_adapt_fep>`
* :doc:`addforce <fix_addforce>`
@ -103,6 +104,7 @@ OPT.
* :doc:`manifoldforce <fix_manifoldforce>`
* :doc:`mdi/engine <fix_mdi_engine>`
* :doc:`meso/move <fix_meso_move>`
* :doc:`mol/swap <fix_mol_swap>`
* :doc:`momentum (k) <fix_momentum>`
* :doc:`momentum/chunk <fix_momentum>`
* :doc:`move <fix_move>`
@ -238,6 +240,7 @@ OPT.
* :doc:`ti/spring <fix_ti_spring>`
* :doc:`tmd <fix_tmd>`
* :doc:`ttm <fix_ttm>`
* :doc:`ttm/grid <fix_ttm>`
* :doc:`ttm/mod <fix_ttm>`
* :doc:`tune/kspace <fix_tune_kspace>`
* :doc:`update/special/bonds <fix_update_special_bonds>`

86
doc/src/Commands_input.rst
View File

@ -1,55 +1,75 @@
LAMMPS input scripts
====================
LAMMPS executes by reading commands from a input script (text file),
one line at a time. When the input script ends, LAMMPS exits. Each
command causes LAMMPS to take some action. It may set an internal
variable, read in a file, or run a simulation. Most commands have
default settings, which means you only need to use the command if you
wish to change the default.
LAMMPS executes calculations by reading commands from a input script (text file), one
line at a time. When the input script ends, LAMMPS exits. This is different
from programs that read and process the entire input before starting a calculation.
Each command causes LAMMPS to take some immediate action without regard
for any commands that may be processed later. Commands may set an
internal variable, read in a file, or run a simulation. These actions
can be grouped into three categories:
a) commands that change a global setting (examples: timestep, newton,
echo, log, thermo, restart),
b) commands that add, modify, remove, or replace "styles" that are
executed during a "run" (examples: pair_style, fix, compute, dump,
thermo_style, pair_modify), and
c) commands that execute a "run" or perform some other computation or
operation (examples: print, run, minimize, temper, write_dump, rerun,
read_data, read_restart)
Commands in category a) have default settings, which means you only
need to use the command if you wish to change the defaults.
In many cases, the ordering of commands in an input script is not
important. However the following rules apply:
important, but can have consequences when the global state is changed
between commands in the c) category. The following rules apply:
(1) LAMMPS does not read your entire input script and then perform a
simulation with all the settings. Rather, the input script is read
one line at a time and each command takes effect when it is read.
Thus this sequence of commands:
simulation with all the settings. Rather, the input script is read
one line at a time and each command takes effect when it is read.
Thus this sequence of commands:
.. code-block:: LAMMPS
.. code-block:: LAMMPS
timestep 0.5
run 100
run 100
timestep 0.5
run 100
run 100
does something different than this sequence:
does something different than this sequence:
.. code-block:: LAMMPS
.. code-block:: LAMMPS
run 100
timestep 0.5
run 100
run 100
timestep 0.5
run 100
In the first case, the specified timestep (0.5 fs) is used for two
simulations of 100 timesteps each. In the second case, the default
timestep (1.0 fs) is used for the first 100 step simulation and a 0.5 fs
timestep is used for the second one.
In the first case, the specified timestep (0.5 fs) is used for two
simulations of 100 timesteps each. In the second case, the default
timestep (1.0 fs) is used for the first 100 step simulation and a
0.5 fs timestep is used for the second one.
(2) Some commands are only valid when they follow other commands. For
example you cannot set the temperature of a group of atoms until atoms
have been defined and a group command is used to define which atoms
belong to the group.
example you cannot set the temperature of a group of atoms until
atoms have been defined and a group command is used to define which
atoms belong to the group.
(3) Sometimes command B will use values that can be set by command A.
This means command A must precede command B in the input script if it
is to have the desired effect. For example, the
:doc:`read_data <read_data>` command initializes the system by setting
up the simulation box and assigning atoms to processors. If default
values are not desired, the :doc:`processors <processors>` and
:doc:`boundary <boundary>` commands need to be used before read_data to
tell LAMMPS how to map processors to the simulation box.
This means command A must precede command B in the input script if
it is to have the desired effect. For example, the :doc:`read_data
<read_data>` command initializes the system by setting up the
simulation box and assigning atoms to processors. If default values
are not desired, the :doc:`processors <processors>` and
:doc:`boundary <boundary>` commands need to be used before read_data
to tell LAMMPS how to map processors to the simulation box.
Many input script errors are detected by LAMMPS and an ERROR or
WARNING message is printed. The :doc:`Errors <Errors>` page gives
more information on what errors mean. The documentation for each
command lists restrictions on how the command can be used.
You can use the :ref:`-skiprun <skiprun>` command line flag
to have LAMMPS skip the execution of any "run", "minimize", or similar
commands to check the entire input for correct syntax to avoid crashes
on typos or syntax errors in long runs.

2
doc/src/Developer.rst
View File

@ -11,10 +11,12 @@ of time and requests from the LAMMPS user community.
:maxdepth: 1
Developer_org
Developer_parallel
Developer_flow
Developer_write
Developer_notes
Developer_plugins
Developer_unittest
Classes
Developer_platform
Developer_utils

120
doc/src/Developer_par_comm.rst Normal file
View File

@ -0,0 +1,120 @@
Communication
^^^^^^^^^^^^^
Following the partitioning scheme in use all per-atom data is
distributed across the MPI processes, which allows LAMMPS to handle very
large systems provided it uses a correspondingly large number of MPI
processes. Since The per-atom data (atom IDs, positions, velocities,
types, etc.) To be able to compute the short-range interactions MPI
processes need not only access to data of atoms they "own" but also
information about atoms from neighboring sub-domains, in LAMMPS referred
to as "ghost" atoms. These are copies of atoms storing required
per-atom data for up to the communication cutoff distance. The green
dashed-line boxes in the :ref:`domain-decomposition` figure illustrate
the extended ghost-atom sub-domain for one processor.
This approach is also used to implement periodic boundary
conditions: atoms that lie within the cutoff distance across a periodic
boundary are also stored as ghost atoms and taken from the periodic
replication of the sub-domain, which may be the same sub-domain, e.g. if
running in serial. As a consequence of this, force computation in
LAMMPS is not subject to minimum image conventions and thus cutoffs may
be larger than half the simulation domain.
.. _ghost-atom-comm:
.. figure:: img/ghost-comm.png
:align: center
ghost atom communication
This figure shows the ghost atom communication patterns between
sub-domains for "brick" (left) and "tiled" communication styles for
2d simulations. The numbers indicate MPI process ranks. Here the
sub-domains are drawn spatially separated for clarity. The
dashed-line box is the extended sub-domain of processor 0 which
includes its ghost atoms. The red- and blue-shaded boxes are the
regions of communicated ghost atoms.
Efficient communication patterns are needed to update the "ghost" atom
data, since that needs to be done at every MD time step or minimization
step. The diagrams of the `ghost-atom-comm` figure illustrate how ghost
atom communication is performed in two stages for a 2d simulation (three
in 3d) for both a regular and irregular partitioning of the simulation
box. For the regular case (left) atoms are exchanged first in the
*x*-direction, then in *y*, with four neighbors in the grid of processor
sub-domains.
In the *x* stage, processor ranks 1 and 2 send owned atoms in their
red-shaded regions to rank 0 (and vice versa). Then in the *y* stage,
ranks 3 and 4 send atoms in their blue-shaded regions to rank 0, which
includes ghost atoms they received in the *x* stage. Rank 0 thus
acquires all its ghost atoms; atoms in the solid blue corner regions
are communicated twice before rank 0 receives them.
For the irregular case (right) the two stages are similar, but a
processor can have more than one neighbor in each direction. In the
*x* stage, MPI ranks 1,2,3 send owned atoms in their red-shaded regions to
rank 0 (and vice versa). These include only atoms between the lower
and upper *y*-boundary of rank 0's sub-domain. In the *y* stage, ranks
4,5,6 send atoms in their blue-shaded regions to rank 0. This may
include ghost atoms they received in the *x* stage, but only if they
are needed by rank 0 to fill its extended ghost atom regions in the
+/-*y* directions (blue rectangles). Thus in this case, ranks 5 and
6 do not include ghost atoms they received from each other (in the *x*
stage) in the atoms they send to rank 0. The key point is that while
the pattern of communication is more complex in the irregular
partitioning case, it can still proceed in two stages (three in 3d)
via atom exchanges with only neighboring processors.
When attributes of owned atoms are sent to neighboring processors to
become attributes of their ghost atoms, LAMMPS calls this a "forward"
communication. On timesteps when atoms migrate to new owning processors
and neighbor lists are rebuilt, each processor creates a list of its
owned atoms which are ghost atoms in each of its neighbor processors.
These lists are used to pack per-atom coordinates (for example) into
message buffers in subsequent steps until the next reneighboring.
A "reverse" communication is when computed ghost atom attributes are
sent back to the processor who owns the atom. This is used (for
example) to sum partial forces on ghost atoms to the complete force on
owned atoms. The order of the two stages described in the
:ref:`ghost-atom-comm` figure is inverted and the same lists of atoms
are used to pack and unpack message buffers with per-atom forces. When
a received buffer is unpacked, the ghost forces are summed to owned atom
forces. As in forward communication, forces on atoms in the four blue
corners of the diagrams are sent, received, and summed twice (once at
each stage) before owning processors have the full force.
These two operations are used many places within LAMMPS aside from
exchange of coordinates and forces, for example by manybody potentials
to share intermediate per-atom values, or by rigid-body integrators to
enable each atom in a body to access body properties. Here are
additional details about how these communication operations are
performed in LAMMPS:
- When exchanging data with different processors, forward and reverse
communication is done using ``MPI_Send()`` and ``MPI_IRecv()`` calls.
If a processor is "exchanging" atoms with itself, only the pack and
unpack operations are performed, e.g. to create ghost atoms across
periodic boundaries when running on a single processor.
- For forward communication of owned atom coordinates, periodic box
lengths are added and subtracted when the receiving processor is
across a periodic boundary from the sender. There is then no need to
apply a minimum image convention when calculating distances between
atom pairs when building neighbor lists or computing forces.
- The cutoff distance for exchanging ghost atoms is typically equal to
the neighbor cutoff. But it can also chosen to be longer if needed,
e.g. half the diameter of a rigid body composed of multiple atoms or
over 3x the length of a stretched bond for dihedral interactions. It
can also exceed the periodic box size. For the regular communication
pattern (left), if the cutoff distance extends beyond a neighbor
processor's sub-domain, then multiple exchanges are performed in the
same direction. Each exchange is with the same neighbor processor,
but buffers are packed/unpacked using a different list of atoms. For
forward communication, in the first exchange a processor sends only
owned atoms. In subsequent exchanges, it sends ghost atoms received
in previous exchanges. For the irregular pattern (right) overlaps of
a processor's extended ghost-atom sub-domain with all other processors
in each dimension are detected.

188
doc/src/Developer_par_long.rst Normal file
View File

@ -0,0 +1,188 @@
Long-range interactions
^^^^^^^^^^^^^^^^^^^^^^^
For charged systems, LAMMPS can compute long-range Coulombic
interactions via the FFT-based particle-particle/particle-mesh (PPPM)
method implemented in :doc:`kspace style pppm and its variants
<kspace_style>`. For that Coulombic interactions are partitioned into
short- and long-range components. The short-ranged portion is computed
in real space as a loop over pairs of charges within a cutoff distance,
using neighbor lists. The long-range portion is computed in reciprocal
space using a kspace style. For the PPPM implementation the simulation
cell is overlaid with a regular FFT grid in 3d. It proceeds in several stages:
a) each atom's point charge is interpolated to nearby FFT grid points,
b) a forward 3d FFT is performed,
c) a convolution operation is performed in reciprocal space,
d) one or more inverse 3d FFTs are performed, and
e) electric field values from grid points near each atom are interpolated to compute
its forces.
For any of the spatial-decomposition partitioning schemes each processor
owns the brick-shaped portion of FFT grid points contained within its
sub-domain. The two interpolation operations use a stencil of grid
points surrounding each atom. To accommodate the stencil size, each
processor also stores a few layers of ghost grid points surrounding its
brick. Forward and reverse communication of grid point values is
performed similar to the corresponding :doc:`atom data communication
<Developer_par_comm>`. In this case, electric field values on owned
grid points are sent to neighboring processors to become ghost point
values. Likewise charge values on ghost points are sent and summed to
values on owned points.
For triclinic simulation boxes, the FFT grid planes are parallel to
the box faces, but the mapping of charge and electric field values
to/from grid points is done in reduced coordinates where the tilted
box is conceptually a unit cube, so that the stencil and FFT
operations are unchanged. However the FFT grid size required for a
given accuracy is larger for triclinic domains than it is for
orthogonal boxes.
.. _fft-parallel:
.. figure:: img/fft-decomp-parallel.png
:align: center
parallel FFT in PPPM
Stages of a parallel FFT for a simulation domain overlaid
with an 8x8x8 3d FFT grid, partitioned across 64 processors.
Within each of the 4 diagrams, grid cells of the same color are
owned by a single processor; for simplicity only cells owned by 4
or 8 of the 64 processors are colored. The two images on the left
illustrate brick-to-pencil communication. The two images on the
right illustrate pencil-to-pencil communication, which in this
case transposes the *y* and *z* dimensions of the grid.
Parallel 3d FFTs require substantial communication relative to their
computational cost. A 3d FFT is implemented by a series of 1d FFTs
along the *x-*, *y-*, and *z-*\ direction of the FFT grid. Thus the FFT
grid cannot be decomposed like atoms into 3 dimensions for parallel
processing of the FFTs but only in 1 (as planes) or 2 (as pencils)
dimensions and in between the steps the grid needs to be transposed to
have the FFT grid portion "owned" by each MPI process complete in the
direction of the 1d FFTs it has to perform. LAMMPS uses the
pencil-decomposition algorithm as shown in the :ref:`fft-parallel` figure.
Initially (far left), each processor owns a brick of same-color grid
cells (actually grid points) contained within in its sub-domain. A
brick-to-pencil communication operation converts this layout to 1d
pencils in the *x*-dimension (center left). Again, cells of the same
color are owned by the same processor. Each processor can then compute
a 1d FFT on each pencil of data it wholly owns using a call to the
configured FFT library. A pencil-to-pencil communication then converts
this layout to pencils in the *y* dimension (center right) which
effectively transposes the *x* and *y* dimensions of the grid, followed
by 1d FFTs in *y*. A final transpose of pencils from *y* to *z* (far
right) followed by 1d FFTs in *z* completes the forward FFT. The data
is left in a *z*-pencil layout for the convolution operation. One or
more inverse FFTs then perform the sequence of 1d FFTs and communication
steps in reverse order; the final layout of resulting grid values is the
same as the initial brick layout.
Each communication operation within the FFT (brick-to-pencil or
pencil-to-pencil or pencil-to-brick) converts one tiling of the 3d grid
to another, where a tiling in this context means an assignment of a
small brick-shaped subset of grid points to each processor, the union of
which comprise the entire grid. The parallel `fftMPI library
<https://lammps.github.io/fftmpi/>`_ written for LAMMPS allows arbitrary
definitions of the tiling so that an irregular partitioning of the
simulation domain can use it directly. Transforming data from one
tiling to another is implemented in `fftMPI` using point-to-point
communication, where each processor sends data to a few other
processors, since each tile in the initial tiling overlaps with a
handful of tiles in the final tiling.
The transformations could also be done using collective communication
across all $P$ processors with a single call to ``MPI_Alltoall()``, but
this is typically much slower. However, for the specialized brick and
pencil tiling illustrated in :ref:`fft-parallel` figure, collective
communication across the entire MPI communicator is not required. In
the example an :math:`8^3` grid with 512 grid cells is partitioned
across 64 processors; each processor owns a 2x2x2 3d brick of grid
cells. The initial brick-to-pencil communication (upper left to upper
right) only requires collective communication within subgroups of 4
processors, as illustrated by the 4 colors. More generally, a
brick-to-pencil communication can be performed by partitioning *P*
processors into :math:`P^{\frac{2}{3}}` subgroups of
:math:`P^{\frac{1}{3}}` processors each. Each subgroup performs
collective communication only within its subgroup. Similarly,
pencil-to-pencil communication can be performed by partitioning *P*
processors into :math:`P^{\frac{1}{2}}` subgroups of
:math:`P^{\frac{1}{2}}` processors each. This is illustrated in the
figure for the :math:`y \Rightarrow z` communication (center). An
eight-processor subgroup owns the front *yz* plane of data and performs
collective communication within the subgroup to transpose from a
*y*-pencil to *z*-pencil layout.
LAMMPS invokes point-to-point communication by default, but also
provides the option of partitioned collective communication when using a
:doc:`kspace_modify collective yes <kspace_modify>` command to switch to
that mode. In the latter case, the code detects the size of the
disjoint subgroups and partitions the single *P*-size communicator into
multiple smaller communicators, each of which invokes collective
communication. Testing on a large IBM Blue Gene/Q machine at Argonne
National Labs showed a significant improvement in FFT performance for
large processor counts; partitioned collective communication was faster
than point-to-point communication or global collective communication
involving all *P* processors.
Here are some additional details about FFTs for long-range and related
grid/particle operations that LAMMPS supports:
- The fftMPI library allows each grid dimension to be a multiple of
small prime factors (2,3,5), and allows any number of processors to
perform the FFT. The resulting brick and pencil decompositions are
thus not always as well-aligned but the size of subgroups of
processors for the two modes of communication (brick/pencil and
pencil/pencil) still scale as :math:`O(P^{\frac{1}{3}})` and
:math:`O(P^{\frac{1}{2}})`.
- For efficiency in performing 1d FFTs, the grid transpose
operations illustrated in Figure \ref{fig:fft} also involve
reordering the 3d data so that a different dimension is contiguous
in memory. This reordering can be done during the packing or
unpacking of buffers for MPI communication.
- For large systems and particularly a large number of MPI processes,
the dominant cost for parallel FFTs is often the communication, not
the computation of 1d FFTs, even though the latter scales as :math:`N
\log(N)` in the number of grid points *N* per grid direction. This is
due to the fact that only a 2d decomposition into pencils is possible
while atom data (and their corresponding short-range force and energy
computations) can be decomposed efficiently in 3d.
This can be addressed by reducing the number of MPI processes involved
in the MPI communication by using :doc:`hybrid MPI + OpenMP
parallelization <Speed_omp>`. This will use OpenMP parallelization
inside the MPI domains and while that may have a lower parallel
efficiency, it reduces the communication overhead.
As an alternative it is also possible to start a :ref:`multi-partition
<partition>` calculation and then use the :doc:`verlet/split
integrator <run_style>` to perform the PPPM computation on a
dedicated, separate partition of MPI processes. This uses an integer
"1:*p*" mapping of *p* sub-domains of the atom decomposition to one
sub-domain of the FFT grid decomposition and where pairwise non-bonded
and bonded forces and energies are computed on the larger partition
and the PPPM kspace computation concurrently on the smaller partition.
- LAMMPS also implements PPPM-based solvers for other long-range
interactions, dipole and dispersion (Lennard-Jones), which can be used
in conjunction with long-range Coulombics for point charges.
- LAMMPS implements a ``GridComm`` class which overlays the simulation
domain with a regular grid, partitions it across processors in a
manner consistent with processor sub-domains, and provides methods for
forward and reverse communication of owned and ghost grid point
values. It is used for PPPM as an FFT grid (as outlined above) and
also for the MSM algorithm which uses a cascade of grid sizes from
fine to coarse to compute long-range Coulombic forces. The GridComm
class is also useful for models where continuum fields interact with
particles. For example, the two-temperature model (TTM) defines heat
transfer between atoms (particles) and electrons (continuum gas) where
spatial variations in the electron temperature are computed by finite
differences of a discretized heat equation on a regular grid. The
:doc:`fix ttm/grid <fix_ttm>` command uses the ``GridComm`` class
internally to perform its grid operations on a distributed grid
instead of the original :doc:`fix ttm <fix_ttm>` which uses a
replicated grid.

159
doc/src/Developer_par_neigh.rst Normal file
View File

@ -0,0 +1,159 @@
Neighbor lists
^^^^^^^^^^^^^^
To compute forces efficiently, each processor creates a Verlet-style
neighbor list which enumerates all pairs of atoms *i,j* (*i* = owned,
*j* = owned or ghost) with separation less than the applicable
neighbor list cutoff distance. In LAMMPS the neighbor lists are stored
in a multiple-page data structure; each page is a contiguous chunk of
memory which stores vectors of neighbor atoms *j* for many *i* atoms.
This allows pages to be incrementally allocated or deallocated in blocks
as needed. Neighbor lists typically consume the most memory of any data
structure in LAMMPS. The neighbor list is rebuilt (from scratch) once
every few timesteps, then used repeatedly each step for force or other
computations. The neighbor cutoff distance is :math:`R_n = R_f +
\Delta_s`, where :math:`R_f` is the (largest) force cutoff defined by
the interatomic potential for computing short-range pairwise or manybody
forces and :math:`\Delta_s` is a "skin" distance that allows the list to
be used for multiple steps assuming that atoms do not move very far
between consecutive time steps. Typically the code triggers
reneighboring when any atom has moved half the skin distance since the
last reneighboring; this and other options of the neighbor list rebuild
can be adjusted with the :doc:`neigh_modify <neigh_modify>` command.
On steps when reneighboring is performed, atoms which have moved outside
their owning processor's sub-domain are first migrated to new processors
via communication. Periodic boundary conditions are also (only)
enforced on these steps to ensure each atom is re-assigned to the
correct processor. After migration, the atoms owned by each processor
are stored in a contiguous vector. Periodically each processor
spatially sorts owned atoms within its vector to reorder it for improved
cache efficiency in force computations and neighbor list building. For
that atoms are spatially binned and then reordered so that atoms in the
same bin are adjacent in the vector. Atom sorting can be disabled or
its settings modified with the :doc:`atom_modify <atom_modify>` command.
.. _neighbor-stencil:
.. figure:: img/neigh-stencil.png
:align: center
neighbor list stencils
A 2d simulation sub-domain (thick black line) and the corresponding
ghost atom cutoff region (dashed blue line) for both orthogonal
(left) and triclinic (right) domains. A regular grid of neighbor
bins (thin lines) overlays the entire simulation domain and need not
align with sub-domain boundaries; only the portion overlapping the
augmented sub-domain is shown. In the triclinic case it overlaps the
bounding box of the tilted rectangle. The blue- and red-shaded bins
represent a stencil of bins searched to find neighbors of a particular
atom (black dot).
To build a local neighbor list in linear time, the simulation domain is
overlaid (conceptually) with a regular 3d (or 2d) grid of neighbor bins,
as shown in the :ref:`neighbor-stencil` figure for 2d models and a
single MPI processor's sub-domain. Each processor stores a set of
neighbor bins which overlap its sub-domain extended by the neighbor
cutoff distance :math:`R_n`. As illustrated, the bins need not align
with processor boundaries; an integer number in each dimension is fit to
the size of the entire simulation box.
Most often LAMMPS builds what it calls a "half" neighbor list where
each *i,j* neighbor pair is stored only once, with either atom *i* or
*j* as the central atom. The build can be done efficiently by using a
pre-computed "stencil" of bins around a central origin bin which
contains the atom whose neighbors are being searched for. A stencil
is simply a list of integer offsets in *x,y,z* of nearby bins
surrounding the origin bin which are close enough to contain any
neighbor atom *j* within a distance :math:`R_n` from any atom *i* in the
origin bin. Note that for a half neighbor list, the stencil can be
asymmetric since each atom only need store half its nearby neighbors.
These stencils are illustrated in the figure for a half list and a bin
size of :math:`\frac{1}{2} R_n`. There are 13 red+blue stencil bins in
2d (for the orthogonal case, 15 for triclinic). In 3d there would be
63, 13 in the plane of bins that contain the origin bin and 25 in each
of the two planes above it in the *z* direction (75 for triclinic). The
reason the triclinic stencil has extra bins is because the bins tile the
bounding box of the entire triclinic domain and thus are not periodic
with respect to the simulation box itself. The stencil and logic for
determining which *i,j* pairs to include in the neighbor list are
altered slightly to account for this.
To build a neighbor list, a processor first loops over its "owned" plus
"ghost" atoms and assigns each to a neighbor bin. This uses an integer
vector to create a linked list of atom indices within each bin. It then
performs a triply-nested loop over its owned atoms *i*, the stencil of
bins surrounding atom *i*'s bin, and the *j* atoms in each stencil bin
(including ghost atoms). If the distance :math:`r_{ij} < R_n`, then
atom *j* is added to the vector of atom *i*'s neighbors.
Here are additional details about neighbor list build options LAMMPS
supports:
- The choice of bin size is an option; a size half of :math:`R_n` has
been found to be optimal for many typical cases. Smaller bins incur
additional overhead to loop over; larger bins require more distance
calculations. Note that for smaller bin sizes, the 2d stencil in the
figure would be more semi-circular in shape (hemispherical in 3d),
with bins near the corners of the square eliminated due to their
distance from the origin bin.
- Depending on the interatomic potential(s) and other commands used in
an input script, multiple neighbor lists and stencils with different
attributes may be needed. This includes lists with different cutoff
distances, e.g. for force computation versus occasional diagnostic
computations such as a radial distribution function, or for the
r-RESPA time integrator which can partition pairwise forces by
distance into subsets computed at different time intervals. It
includes "full" lists (as opposed to half lists) where each *i,j* pair
appears twice, stored once with *i* and *j*, and which use a larger
symmetric stencil. It also includes lists with partial enumeration of
ghost atom neighbors. The full and ghost-atom lists are used by
various manybody interatomic potentials. Lists may also use different
criteria for inclusion of a pair interaction. Typically this simply
depends only on the distance between two atoms and the cutoff
distance. But for finite-size coarse-grained particles with
individual diameters (e.g. polydisperse granular particles), it can
also depend on the diameters of the two particles.
- When using :doc:`pair style hybrid <pair_hybrid>` multiple sub-lists
of the master neighbor list for the full system need to be generated,
one for each sub-style, which contains only the *i,j* pairs needed to
compute interactions between subsets of atoms for the corresponding
potential. This means not all *i* or *j* atoms owned by a processor
are included in a particular sub-list.
- Some models use different cutoff lengths for pairwise interactions
between different kinds of particles which are stored in a single
neighbor list. One example is a solvated colloidal system with large
colloidal particles where colloid/colloid, colloid/solvent, and
solvent/solvent interaction cutoffs can be dramatically different.
Another is a model of polydisperse finite-size granular particles;
pairs of particles interact only when they are in contact with each
other. Mixtures with particle size ratios as high as 10-100x may be
used to model realistic systems. Efficient neighbor list building
algorithms for these kinds of systems are available in LAMMPS. They
include a method which uses different stencils for different cutoff
lengths and trims the stencil to only include bins that straddle the
cutoff sphere surface. More recently a method which uses both
multiple stencils and multiple bin sizes was developed; it builds
neighbor lists efficiently for systems with particles of any size
ratio, though other considerations (timestep size, force computations)
may limit the ability to model systems with huge polydispersity.
- For small and sparse systems and as a fallback method, LAMMPS also
supports neighbor list construction without binning by using a full
:math:`O(N^2)` loop over all *i,j* atom pairs in a sub-domain when
using the :doc:`neighbor nsq <neighbor>` command.
- Dependent on the "pair" setting of the :doc:`newton <newton>` command,
the "half" neighbor lists may contain **all** pairs of atoms where
atom *j* is a ghost atom (i.e. when the newton pair setting is *off*)
For the newton pair *on* setting the atom *j* is only added to the
list if its *z* coordinate is larger, or if equal the *y* coordinate
is larger, and that is equal, too, the *x* coordinate is larger. For
homogeneously dense systems that will result in picking neighbors from
a same size sector in always the same direction relative to the
"owned" atom and thus it should lead to similar length neighbor lists
and thus reduce the chance of a load imbalance.

114
doc/src/Developer_par_openmp.rst Normal file
View File

@ -0,0 +1,114 @@
OpenMP Parallelism
^^^^^^^^^^^^^^^^^^
The styles in the INTEL, KOKKOS, and OPENMP package offer to use OpenMP
thread parallelism to predominantly distribute loops over local data
and thus follow an orthogonal parallelization strategy to the
decomposition into spatial domains used by the :doc:`MPI partitioning
<Developer_par_part>`. For clarity, this section discusses only the
implementation in the OPENMP package as it is the simplest. The INTEL
and KOKKOS package offer additional options and are more complex since
they support more features and different hardware like co-processors
or GPUs.
One of the key decisions when implementing the OPENMP package was to
keep the changes to the source code small, so that it would be easier to
maintain the code and keep it in sync with the non-threaded standard
implementation. this is achieved by a) making the OPENMP version a
derived class from the regular version (e.g. ``PairLJCutOMP`` from
``PairLJCut``) and overriding only methods that are multi-threaded or
need to be modified to support multi-threading (similar to what was done
in the OPT package), b) keeping the structure in the modified code very
similar so that side-by-side comparisons are still useful, and c)
offloading additional functionality and multi-thread support functions
into three separate classes ``ThrOMP``, ``ThrData``, and ``FixOMP``.
``ThrOMP`` provides additional, multi-thread aware functionality not
available in the corresponding base class (e.g. ``Pair`` for
``PairLJCutOMP``) like multi-thread aware variants of the "tally"
functions. Those functions are made available through multiple
inheritance so those new functions have to have unique names to avoid
ambiguities; typically ``_thr`` is appended to the name of the function.
``ThrData`` is a classes that manages per-thread data structures.
It is used instead of extending the corresponding storage to per-thread
arrays to avoid slowdowns due to "false sharing" when multiple threads
update adjacent elements in an array and thus force the CPU cache lines
to be reset and re-fetched. ``FixOMP`` finally manages the "multi-thread
state" like settings and access to per-thread storage, it is activated
by the :doc:`package omp <package>` command.
Avoiding data races
"""""""""""""""""""
A key problem when implementing thread parallelism in an MD code is
to avoid data races when updating accumulated properties like forces,
energies, and stresses. When interactions are computed, they always
involve multiple atoms and thus there are race conditions when multiple
threads want to update per-atom data of the same atoms. Five possible
strategies have been considered to avoid this:
1) restructure the code so that there is no overlapping access possible
when computing in parallel, e.g. by breaking lists into multiple
parts and synchronizing threads in between.
2) have each thread be "responsible" for a specific group of atoms and
compute these interactions multiple times, once on each thread that
is responsible for a given atom and then have each thread only update
the properties of this atom.
3) use mutexes around functions and regions of code where the data race
could happen
4) use atomic operations when updating per-atom properties
5) use replicated per-thread data structures to accumulate data without
conflicts and then use a reduction to combine those results into the
data structures used by the regular style.
Option 5 was chosen for the OPENMP package because it would retain the
performance for the case of 1 thread and the code would be more
maintainable. Option 1 would require extensive code changes,
particularly to the neighbor list code; options 2 would have incurred a
2x or more performance penalty for the serial case; option 3 causes
significant overhead and would enforce serialization of operations in
inner loops and thus defeat the purpose of multi-threading; option 4
slows down the serial case although not quite as bad as option 2. The
downside of option 5 is that the overhead of the reduction operations
grows with the number of threads used, so there would be a crossover
point where options 2 or 4 would result in faster executing. That is
why option 2 for example is used in the GPU package because a GPU is a
processor with a massive number of threads. However, since the MPI
parallelization is generally more effective for typical MD systems, the
expectation is that thread parallelism is only used for a smaller number
of threads (2-8). At the time of its implementation, that number was
equivalent to the number of CPU cores per CPU socket on high-end
supercomputers.
Thus arrays like the force array are dimensioned to the number of atoms
times the number of threads when enabling OpenMP support and inside the
compute functions a pointer to a different chunk is obtained by each thread.
Similarly, accumulators like potential energy or virial are kept in
per-thread instances of the ``ThrData`` class and then only reduced and
stored in their global counterparts at the end of the force computation.
Loop scheduling
"""""""""""""""
Multi-thread parallelization is applied by distributing (outer) loops
statically across threads. Typically this would be the loop over local
atoms *i* when processing *i,j* pairs of atoms from a neighbor list.
The design of the neighbor list code results in atoms having a similar
number of neighbors for homogeneous systems and thus load imbalances
across threads are not common and typically happen for systems where
also the MPI parallelization would be unbalanced, which would typically
have a more pronounced impact on the performance. This same loop
scheduling scheme can also be applied to the reduction operations on
per-atom data to try and reduce the overhead of the reduction operation.
Neighbor list parallelization
"""""""""""""""""""""""""""""
In addition to the parallelization of force computations, also the
generation of the neighbor lists is parallelized. As explained
previously, neighbor lists are built by looping over "owned" atoms and
storing the neighbors in "pages". In the OPENMP variants of the
neighbor list code, each thread operates on a different chunk of "owned"
atoms and allocates and fills its own set of pages with neighbor list
data. This is achieved by each thread keeping its own instance of the
:cpp:class:`MyPage <LAMMPS_NS::MyPage>` page allocator class.

89
doc/src/Developer_par_part.rst Normal file
View File

@ -0,0 +1,89 @@
Partitioning
^^^^^^^^^^^^
The underlying spatial decomposition strategy used by LAMMPS for
distributed-memory parallelism is set with the :doc:`comm_style command
<comm_style>` and can be either "brick" (a regular grid) or "tiled".
.. _domain-decomposition:
.. figure:: img/domain-decomp.png
:align: center
domain decomposition
This figure shows the different kinds of domain decomposition used
for MPI parallelization: "brick" on the left with an orthogonal
(left) and a triclinic (middle) simulation domain, and a "tiled"
decomposition (right). The black lines show the division into
sub-domains and the contained atoms are "owned" by the corresponding
MPI process. The green dashed lines indicate how sub-domains are
extended with "ghost" atoms up to the communication cutoff distance.
The LAMMPS simulation box is a 3d or 2d volume, which can be orthogonal
or triclinic in shape, as illustrated in the :ref:`domain-decomposition`
figure for the 2d case. Orthogonal means the box edges are aligned with
the *x*, *y*, *z* Cartesian axes, and the box faces are thus all
rectangular. Triclinic allows for a more general parallelepiped shape
in which edges are aligned with three arbitrary vectors and the box
faces are parallelograms. In each dimension box faces can be periodic,
or non-periodic with fixed or shrink-wrapped boundaries. In the fixed
case, atoms which move outside the face are deleted; shrink-wrapped
means the position of the box face adjusts continuously to enclose all
the atoms.
For distributed-memory MPI parallelism, the simulation box is spatially
decomposed (partitioned) into non-overlapping sub-domains which fill the
box. The default partitioning, "brick", is most suitable when atom
density is roughly uniform, as shown in the left-side images of the
:ref:`domain-decomposition` figure. The sub-domains comprise a regular
grid and all sub-domains are identical in size and shape. Both the
orthogonal and triclinic boxes can deform continuously during a
simulation, e.g. to compress a solid or shear a liquid, in which case
the processor sub-domains likewise deform.
For models with non-uniform density, the number of particles per
processor can be load-imbalanced with the default partitioning. This
reduces parallel efficiency, as the overall simulation rate is limited
by the slowest processor, i.e. the one with the largest computational
load. For such models, LAMMPS supports multiple strategies to reduce
the load imbalance:
- The processor grid decomposition is by default based on the simulation
cell volume and tries to optimize the volume to surface ratio for the sub-domains.
This can be changed with the :doc:`processors command <processors>`.
- The parallel planes defining the size of the sub-domains can be shifted
with the :doc:`balance command <balance>`. Which can be done in addition
to choosing a more optimal processor grid.
- The recursive bisectioning algorithm in combination with the "tiled"
communication style can produce a partitioning with equal numbers of
particles in each sub-domain.
.. |decomp1| image:: img/decomp-regular.png
:width: 24%
.. |decomp2| image:: img/decomp-processors.png
:width: 24%
.. |decomp3| image:: img/decomp-balance.png
:width: 24%
.. |decomp4| image:: img/decomp-rcb.png
:width: 24%
|decomp1| |decomp2| |decomp3| |decomp4|
The pictures above demonstrate different decompositions for a 2d system
with 12 MPI ranks. The atom colors indicate the load imbalance of each
sub-domain with green being optimal and red the least optimal.
Due to the vacuum in the system, the default decomposition is unbalanced
with several MPI ranks without atoms (left). By forcing a 1x12x1
processor grid, every MPI rank does computations now, but number of
atoms per sub-domain is still uneven and the thin slice shape increases
the amount of communication between sub-domains (center left). With a
2x6x1 processor grid and shifting the sub-domain divisions, the load
imbalance is further reduced and the amount of communication required
between sub-domains is less (center right). And using the recursive
bisectioning leads to further improved decomposition (right).

28
doc/src/Developer_parallel.rst Normal file
View File

@ -0,0 +1,28 @@
Parallel algorithms
-------------------
LAMMPS is designed to enable running simulations in parallel using the
MPI parallel communication standard with distributed data via domain
decomposition. The parallelization aims to be efficient result in good
strong scaling (= good speedup for the same system) and good weak
scaling (= the computational cost of enlarging the system is
proportional to the system size). Additional parallelization using GPUs
or OpenMP can also be applied within the sub-domain assigned to an MPI
process. For clarity, most of the following illustrations show the 2d
simulation case. The underlying algorithms in those cases, however,
apply to both 2d and 3d cases equally well.
.. note::
The text and most of the figures in this chapter were adapted
for the manual from the section on parallel algorithms in the
:ref:`new LAMMPS paper <lammps_paper>`.
.. toctree::
:maxdepth: 1
Developer_par_part
Developer_par_comm
Developer_par_neigh
Developer_par_long
Developer_par_openmp

152
doc/src/Developer_platform.rst Normal file
View File

@ -0,0 +1,152 @@
Platform abstraction functions
------------------------------
The ``platform`` sub-namespace inside the ``LAMMPS_NS`` namespace
provides a collection of wrapper and convenience functions and utilities
that perform common tasks for which platform specific code would be
required or for which a more high-level abstraction would be convenient
and reduce duplicated code. This reduces redundant implementations and
encourages consistent behavior and thus has some overlap with the
:doc:`"utils" sub-namespace <Developer_utils>`.
Time functions
^^^^^^^^^^^^^^
.. doxygenfunction:: cputime
:project: progguide
.. doxygenfunction:: walltime
:project: progguide
.. doxygenfunction:: usleep
:project: progguide
Platform information functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenfunction:: os_info
:project: progguide
.. doxygenfunction:: compiler_info
:project: progguide
.. doxygenfunction:: cxx_standard
:project: progguide
.. doxygenfunction:: openmp_standard
:project: progguide
.. doxygenfunction:: mpi_vendor
:project: progguide
.. doxygenfunction:: mpi_info
:project: progguide
.. doxygenfunction:: compress_info
:project: progguide
File and path functions and global constants
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenvariable:: filepathsep
:project: progguide
.. doxygenvariable:: pathvarsep
:project: progguide
.. doxygenfunction:: guesspath
:project: progguide
.. doxygenfunction:: path_basename
:project: progguide
.. doxygenfunction:: path_join
:project: progguide
.. doxygenfunction:: file_is_readable
:project: progguide
.. doxygenfunction:: is_console
:project: progguide
.. doxygenfunction:: path_is_directory
:project: progguide
.. doxygenfunction:: current_directory
:project: progguide
.. doxygenfunction:: list_directory
:project: progguide
.. doxygenfunction:: chdir
:project: progguide
.. doxygenfunction:: mkdir
:project: progguide
.. doxygenfunction:: rmdir
:project: progguide
.. doxygenfunction:: unlink
:project: progguide
Standard I/O function wrappers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenvariable:: END_OF_FILE
:project: progguide
.. doxygenfunction:: ftell
:project: progguide
.. doxygenfunction:: fseek
:project: progguide
.. doxygenfunction:: ftruncate
:project: progguide
.. doxygenfunction:: popen
:project: progguide
.. doxygenfunction:: pclose
:project: progguide
Environment variable functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenfunction:: putenv
:project: progguide
.. doxygenfunction:: list_pathenv
:project: progguide
.. doxygenfunction:: find_exe_path
:project: progguide
Dynamically loaded object or library functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenfunction:: dlopen
:project: progguide
.. doxygenfunction:: dlclose
:project: progguide
.. doxygenfunction:: dlsym
:project: progguide
.. doxygenfunction:: dlerror
:project: progguide
Compressed file I/O functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenfunction:: has_compress_extension
:project: progguide
.. doxygenfunction:: compressed_read
:project: progguide
.. doxygenfunction:: compressed_write
:project: progguide

37
doc/src/Developer_utils.rst
View File

@ -7,7 +7,9 @@ a collection of convenience functions and utilities that perform common
tasks that are required repeatedly throughout the LAMMPS code like
reading or writing to files with error checking or translation of
strings into specific types of numbers with checking for validity. This
reduces redundant implementations and encourages consistent behavior.
reduces redundant implementations and encourages consistent behavior and
thus has some overlap with the :doc:`"platform" sub-namespace
<Developer_platform>`.
I/O with status check and similar functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -60,6 +62,9 @@ silently returning the result of a partial conversion or zero in cases
where the string is not a valid number. This behavior allows to more
easily detect typos or issues when processing input files.
Similarly the :cpp:func:`logical() <LAMMPS_NS::utils::logical>` function
will convert a string into a boolean and will only accept certain words.
The *do_abort* flag should be set to ``true`` in case this function
is called only on a single MPI rank, as that will then trigger the
a call to ``Error::one()`` for errors instead of ``Error::all()``
@ -83,6 +88,9 @@ strings for compliance without conversion.
.. doxygenfunction:: tnumeric
:project: progguide
.. doxygenfunction:: logical
:project: progguide
String processing
^^^^^^^^^^^^^^^^^
@ -95,6 +103,12 @@ and parsing files or arguments.
.. doxygenfunction:: strdup
:project: progguide
.. doxygenfunction:: lowercase
:project: progguide
.. doxygenfunction:: uppercase
:project: progguide
.. doxygenfunction:: trim
:project: progguide
@ -137,21 +151,6 @@ and parsing files or arguments.
.. doxygenfunction:: is_double
:project: progguide
File and path functions
^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenfunction:: guesspath
:project: progguide
.. doxygenfunction:: path_basename
:project: progguide
.. doxygenfunction:: path_join
:project: progguide
.. doxygenfunction:: file_is_readable
:project: progguide
Potential file functions
^^^^^^^^^^^^^^^^^^^^^^^^
@ -203,9 +202,15 @@ Convenience functions
.. doxygenfunction:: date2num
:project: progguide
.. doxygenfunction:: current_date
:project: progguide
Customized standard functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. doxygenfunction:: binary_search
:project: progguide
.. doxygenfunction:: merge_sort
:project: progguide

4
doc/src/Developer_write.rst
View File

@ -29,7 +29,9 @@ of code in the header before include guards:
.. code-block:: c
#ifdef FIX_CLASS
FixStyle(print/vel,FixPrintVel)
// clang-format off
FixStyle(print/vel,FixPrintVel);
// clang-format on
#else
/* the definition of the FixPrintVel class comes here */
...

3
doc/src/Errors_debug.rst
View File

@ -40,11 +40,10 @@ We use it to show how to identify the origin of a segmentation fault.
After recompiling LAMMPS and running the input you should get something like this:
.. code-block:
.. code-block::
$ ./lmp -in in.melt
LAMMPS (19 Mar 2020)
OMP_NUM_THREADS environment is not set. Defaulting to 1 thread. (src/comm.cpp:94)
using 1 OpenMP thread(s) per MPI task
Lattice spacing in x,y,z = 1.6796 1.6796 1.6796
Created orthogonal box = (0 0 0) to (16.796 16.796 16.796)

12
doc/src/Errors_messages.rst
View File

@ -714,7 +714,7 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
*Cannot create/grow a vector/array of pointers for %s*
LAMMPS code is making an illegal call to the templated memory
allocaters, to create a vector or array of pointers.
allocators, to create a vector or array of pointers.
*Cannot create_atoms after reading restart file with per-atom info*
The per-atom info was stored to be used when by a fix that you may
@ -7879,19 +7879,19 @@ keyword to allow for additional bonds to be formed
*Unexpected end of -reorder file*
Self-explanatory.
*Unexpected empty line in AngleCoeffs section*
*Unexpected empty line in Angle Coeffs section*
Read a blank line where there should be coefficient data.
*Unexpected empty line in BondCoeffs section*
*Unexpected empty line in Bond Coeffs section*
Read a blank line where there should be coefficient data.
*Unexpected empty line in DihedralCoeffs section*
*Unexpected empty line in Dihedral Coeffs section*
Read a blank line where there should be coefficient data.
*Unexpected empty line in ImproperCoeffs section*
*Unexpected empty line in Improper Coeffs section*
Read a blank line where there should be coefficient data.
*Unexpected empty line in PairCoeffs section*
*Unexpected empty line in Pair Coeffs section*
Read a blank line where there should be coefficient data.
*Unexpected end of custom file*

8
doc/src/Examples.rst
View File

@ -27,7 +27,7 @@ be quickly post-processed into a movie using commands described on the
:doc:`dump image <dump_image>` doc page.
Animations of many of the examples can be viewed on the Movies section
of the `LAMMPS web site <https://www.lammps.org/movies.html>`_.
of the `LAMMPS website <https://www.lammps.org/movies.html>`_.
There are two kinds of sub-directories in the examples folder. Lower
case named directories contain one or a few simple, quick-to-run
@ -82,7 +82,7 @@ Lowercase directories
+-------------+------------------------------------------------------------------+
| friction | frictional contact of spherical asperities between 2d surfaces |
+-------------+------------------------------------------------------------------+
| gcmc | Grand Canonical Monte Carlo (GCMC) via the fix gcmc command |
| mc | Monte Carlo features via fix gcmc, widom and other commands |
+-------------+------------------------------------------------------------------+
| granregion | use of fix wall/region/gran as boundary on granular particles |
+-------------+------------------------------------------------------------------+
@ -171,7 +171,7 @@ Running the simulation produces the files *dump.indent* and
*log.lammps*\ . You can visualize the dump file of snapshots with a
variety of third-party tools highlighted on the
`Visualization <https://www.lammps.org/viz.html>`_ page of the LAMMPS
web site.
website.
If you uncomment the :doc:`dump image <dump_image>` line(s) in the input
script a series of JPG images will be produced by the run (assuming
@ -207,7 +207,7 @@ Uppercase directories
+------------+--------------------------------------------------------------------------------------------------+
| KAPPA | compute thermal conductivity via several methods |
+------------+--------------------------------------------------------------------------------------------------+
| MC | using LAMMPS in a Monte Carlo mode to relax the energy of a system |
| MC-LOOP | using LAMMPS in a Monte Carlo mode to relax the energy of a system in a input script loop |
+------------+--------------------------------------------------------------------------------------------------+
| PACKAGES | examples for specific packages and contributed commands |
+------------+--------------------------------------------------------------------------------------------------+

1
doc/src/Howto.rst
View File

@ -54,6 +54,7 @@ Analysis howto
Howto_kappa
Howto_viscosity
Howto_diffusion
Howto_structured_data
Force fields howto
==================

133
doc/src/Howto_github.rst
View File

@ -7,11 +7,11 @@ LAMMPS GitHub tutorial
This document describes the process of how to use GitHub to integrate
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 reacquaint yourself with some
of the more advanced git features used below.
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
more advanced git features used below.
As of fall 2016, submitting contributions to LAMMPS via pull requests
on GitHub is the preferred option for integrating contributed features
@ -37,15 +37,15 @@ username or e-mail address and password.
**Forking the repository**
To get changes into LAMMPS, you need to first fork the `lammps/lammps`
repository on GitHub. At the time of writing, *master* is the preferred
repository on GitHub. At the time of writing, *develop* is the preferred
target branch. Thus go to `LAMMPS on GitHub <https://github.com/lammps/lammps>`_
and make sure branch is set to "master", as shown in the figure below.
and make sure branch is set to "develop", as shown in the figure below.
.. image:: JPG/tutorial_branch.png
:align: center
If it is not, use the button to change it to *master*\ . Once it is, use the
fork button to create a fork.
If it is not, use the button to change it to *develop*. Once it is, use
the fork button to create a fork.
.. image:: JPG/tutorial_fork.png
:align: center
@ -64,11 +64,12 @@ LAMMPS development.
**Adding changes to your own fork**
Additions to the upstream version of LAMMPS are handled using *feature
branches*\ . For every new feature, a so-called feature branch is
branches*. For every new feature, a so-called feature branch is
created, which contains only those modification relevant to one specific
feature. For example, adding a single fix would consist of creating a
branch with only the fix header and source file and nothing else. It is
explained in more detail here: `feature branch workflow <https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow>`_.
explained in more detail here: `feature branch workflow
<https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow>`_.
**Feature branches**
@ -94,8 +95,8 @@ The above command copies ("clones") the git repository to your local
machine to a directory with the name you chose. If none is given, it will
default to "lammps". Typical names are "mylammps" or something similar.
You can use this local clone to make changes and
test them without interfering with the repository on GitHub.
You can use this local clone to make changes and test them without
interfering with the repository on GitHub.
To pull changes from upstream into this copy, you can go to the directory
and use git pull:
@ -103,28 +104,45 @@ and use git pull:
.. code-block:: bash
$ cd mylammps
$ git checkout master
$ git pull https://github.com/lammps/lammps
$ git checkout develop
$ git pull https://github.com/lammps/lammps develop
You can also add this URL as a remote:
.. code-block:: bash
$ git remote add lammps_upstream https://www.github.com/lammps/lammps
$ git remote add upstream https://www.github.com/lammps/lammps
At this point, you typically make a feature branch from the updated master
From then on you can update your upstream branches with:
.. code-block:: bash
$ git fetch upstream
and then refer to the upstream repository branches with
`upstream/develop` or `upstream/release` and so on.
At this point, you typically make a feature branch from the updated
branch for the feature you want to work on. This tutorial contains the
workflow that updated this tutorial, and hence we will call the branch
"github-tutorial-update":
.. code-block:: bash
$ git checkout -b github-tutorial-update master
$ git fetch upstream
$ git checkout -b github-tutorial-update upstream/develop
Now that we have changed branches, we can make our changes to our local
repository. Just remember that if you want to start working on another,
unrelated feature, you should switch branches!
.. note::
Committing changes to the *develop*, *release*, or *stable* branches
is strongly discouraged. While it may be convenient initially, it
will create more work in the long run. Various texts and tutorials
on using git effectively discuss the motivation for this.
**After changes are made**
After everything is done, add the files to the branch and commit them:
@ -287,28 +305,32 @@ After each push, the automated checks are run again.
LAMMPS developers may add labels to your pull request to assign it to
categories (mostly for bookkeeping purposes), but a few of them are
important: needs_work, work_in_progress, test-for-regression, and
full-regression-test. The first two indicate, that your pull request
is not considered to be complete. With "needs_work" the burden is on
exclusively on you; while "work_in_progress" can also mean, that a
LAMMPS developer may want to add changes. Please watch the comments
to the pull requests. The two "test" labels are used to trigger
extended tests before the code is merged. This is sometimes done by
LAMMPS developers, if they suspect that there may be some subtle
side effects from your changes. It is not done by default, because
those tests are very time consuming.
important: *needs_work*, *work_in_progress*, *run_tests*,
*test_for_regression*, and *ready_for_merge*. The first two indicate,
that your pull request is not considered to be complete. With
"needs_work" the burden is on exclusively on you; while
"work_in_progress" can also mean, that a LAMMPS developer may want to
add changes. Please watch the comments to the pull requests. The two
"test" labels are used to trigger extended tests before the code is
merged. This is sometimes done by LAMMPS developers, if they suspect
that there may be some subtle side effects from your changes. It is not
done by default, because those tests are very time consuming. The
*ready_for_merge* label is usually attached when the LAMMPS developer
assigned to the pull request considers this request complete and to
trigger a final full test evaluation.
**Reviews**
As of Summer 2018, a pull request needs at least 1 approving review
from a LAMMPS developer with write access to the repository.
In case your changes touch code that certain developers are associated
with, they are auto-requested by the GitHub software. Those associations
are set in the file
`.github/CODEOWNERS <https://github.com/lammps/lammps/blob/master/.github/CODEOWNERS>`_
Thus if you want to be automatically notified to review when anybody
changes files or packages, that you have contributed to LAMMPS, you can
add suitable patterns to that file, or a LAMMPS developer may add you.
As of Fall 2021, a pull request needs to pass all automatic tests and at
least 1 approving review from a LAMMPS developer with write access to
the repository before it is eligible for merging. In case your changes
touch code that certain developers are associated with, they are
auto-requested by the GitHub software. Those associations are set in
the file `.github/CODEOWNERS
<https://github.com/lammps/lammps/blob/develop/.github/CODEOWNERS>`_ Thus
if you want to be automatically notified to review when anybody changes
files or packages, that **you** have contributed to LAMMPS, you can add
suitable patterns to that file, or a LAMMPS developer may add you.
Otherwise, you can also manually request reviews from specific developers,
or LAMMPS developers - in their assessment of your pull request - may
@ -329,7 +351,7 @@ LAMMPS developer (including him/herself) or c) Axel Kohlmeyer (akohlmey).
After the review, the developer can choose to implement changes directly
or suggest them to you.
* Case c) means that the pull request has been assigned to the developer
overseeing the merging of pull requests into the master branch.
overseeing the merging of pull requests into the *develop* branch.
In this case, Axel assigned the tutorial to Steve:
@ -351,11 +373,11 @@ Sometimes, however, you might not feel comfortable having other people
push changes into your own branch, or maybe the maintainers are not sure
their idea was the right one. In such a case, they can make changes,
reassign you as the assignee, and file a "reverse pull request", i.e.
file a pull request in your GitHub repository to include changes in the
branch, that you have submitted as a pull request yourself. In that
case, you can choose to merge their changes back into your branch,
possibly make additional changes or corrections and proceed from there.
It looks something like this:
file a pull request in **your** forked GitHub repository to include
changes in the branch, that you have submitted as a pull request
yourself. In that case, you can choose to merge their changes back into
your branch, possibly make additional changes or corrections and proceed
from there. It looks something like this:
.. image:: JPG/tutorial_reverse_pull_request.png
:align: center
@ -419,7 +441,7 @@ This merge also shows up on the lammps GitHub page:
**After a merge**
When everything is fine, the feature branch is merged into the master branch:
When everything is fine, the feature branch is merged into the *develop* branch:
.. image:: JPG/tutorial_merged.png
:align: center
@ -433,8 +455,8 @@ branch!
.. code-block:: bash
$ git checkout master
$ git pull master
$ git checkout develop
$ git pull https://github.com/lammps/lammps develop
$ git branch -d github-tutorial-update
If you do not pull first, it is not really a problem but git will warn
@ -442,6 +464,7 @@ you at the next statement that you are deleting a local branch that
was not yet fully merged into HEAD. This is because git does not yet
know your branch just got merged into LAMMPS upstream. If you
first delete and then pull, everything should still be fine.
You can display all branches that are fully merged by:
Finally, if you delete the branch locally, you might want to push this
to your remote(s) as well:
@ -453,14 +476,14 @@ to your remote(s) as well:
**Recent changes in the workflow**
Some changes to the workflow are not captured in this tutorial. For
example, in addition to the master branch, to which all new features
should be submitted, there is now also an "unstable" and a "stable"
branch; these have the same content as "master", but are only updated
after a patch release or stable release was made.
Furthermore, the naming of the patches now follow the pattern
"patch_<Day><Month><Year>" to simplify comparisons between releases.
Finally, all patches and submissions are subject to automatic testing
and code checks to make sure they at the very least compile.
example, in addition to the *develop* branch, to which all new features
should be submitted, there is also a *release* and a *stable* branch;
these have the same content as *develop*, but are only updated after a
patch release or stable release was made. Furthermore, the naming of
the patches now follow the pattern "patch_<Day><Month><Year>" to
simplify comparisons between releases. Finally, all patches and
submissions are subject to automatic testing and code checks to make
sure they at the very least compile.
A discussion of the LAMMPS developer GitHub workflow can be found in the file
`doc/github-development-workflow.md <https://github.com/lammps/lammps/blob/master/doc/github-development-workflow.md>`_
`doc/github-development-workflow.md <https://github.com/lammps/lammps/blob/develop/doc/github-development-workflow.md>`_

154
doc/src/Howto_structured_data.rst Normal file
View File

@ -0,0 +1,154 @@
Output structured data from LAMMPS
##################################
LAMMPS can output structured data with the :doc:`print <print>` and :doc:`fix
print <fix_print>` command. This gives you flexibility since you can build
custom data formats that contain system properties, thermo data, and variables
values. This output can be directed to the screen and/or to a file for post
processing.
Writing the current system state, thermo data, variable values
==============================================================
Use the :doc:`print <print>` command to output the current system state, which
can include system properties, thermo data and variable values.
YAML
----
.. code-block:: LAMMPS
print """---
timestep: $(step)
pe: $(pe)
ke: $(ke)""" file current_state.yaml screen no
.. code-block:: yaml
:caption: current_state.yaml
---
timestep: 250
pe: -4.7774327356321810711
ke: 2.4962152903997174569
JSON
----
.. code-block:: LAMMPS
print """{
"timestep": $(step),
"pe": $(pe),
"ke": $(ke)
}""" file current_state.json screen no
.. code-block:: JSON
:caption: current_state.json
{
"timestep": 250,
"pe": -4.7774327356321810711,
"ke": 2.4962152903997174569
}
Writing continuous data during a simulation
===========================================
The :doc:`fix print <fix_print>` command allows you to output an arbitrary string at defined times during a simulation run.
YAML
----
.. code-block:: LAMMPS
fix extra all print 50 """
- timestep: $(step)
pe: $(pe)
ke: $(ke)""" file output.yaml screen no
.. code-block:: yaml
:caption: output.yaml
# Fix print output for fix extra
- timestep: 0
pe: -6.77336805325924729
ke: 4.4988750000000026219
- timestep: 50
pe: -4.8082494418323200591
ke: 2.5257981827119797558
- timestep: 100
pe: -4.7875608875581505686
ke: 2.5062598821985102582
- timestep: 150
pe: -4.7471033686005483787
ke: 2.466095925545450207
- timestep: 200
pe: -4.7509052858544134068
ke: 2.4701136792591693592
- timestep: 250
pe: -4.7774327356321810711
ke: 2.4962152903997174569
Post-processing of YAML files can be easily be done with Python and other
scripting languages. In case of Python the `yaml` package allows you to load the
data files and obtain a list of dictionaries.
.. code-block:: python
import yaml
with open("output.yaml") as f:
data = yaml.load(f, Loader=yaml.FullLoader)
print(data)
.. code-block::
[{'timestep': 0, 'pe': -6.773368053259247, 'ke': 4.498875000000003}, {'timestep': 50, 'pe': -4.80824944183232, 'ke': 2.5257981827119798}, {'timestep': 100, 'pe': -4.787560887558151, 'ke': 2.5062598821985103}, {'timestep': 150, 'pe': -4.747103368600548, 'ke': 2.46609592554545}, {'timestep': 200, 'pe': -4.750905285854413, 'ke': 2.4701136792591694}, {'timestep': 250, 'pe': -4.777432735632181, 'ke': 2.4962152903997175}]
Line Delimited JSON (LD-JSON)
-----------------------------
The JSON format itself is very strict when it comes to delimiters. For continuous
output/streaming data it is beneficial use the *line delimited JSON* format.
Each line represents one JSON object.
.. code-block:: LAMMPS
fix extra all print 50 """{"timestep": $(step), "pe": $(pe), "ke": $(ke)}""" title "" file output.json screen no
.. code-block:: json
:caption: output.json
{"timestep": 0, "pe": -6.77336805325924729, "ke": 4.4988750000000026219}
{"timestep": 50, "pe": -4.8082494418323200591, "ke": 2.5257981827119797558}
{"timestep": 100, "pe": -4.7875608875581505686, "ke": 2.5062598821985102582}
{"timestep": 150, "pe": -4.7471033686005483787, "ke": 2.466095925545450207}
{"timestep": 200, "pe": -4.7509052858544134068, "ke": 2.4701136792591693592}
{"timestep": 250, "pe": -4.7774327356321810711, "ke": 2.4962152903997174569}
One simple way to load this data into a Python script is to use the `pandas`
package. It can directly load these files into a data frame:
.. code-block:: python
import pandas as pd
data = pd.read_json('output.json', lines=True)
print(data)
.. code-block:: bash
timestep pe ke
0 0 -6.773368 4.498875
1 50 -4.808249 2.525798
2 100 -4.787561 2.506260
3 150 -4.747103 2.466096
4 200 -4.750905 2.470114
5 250 -4.777433 2.496215

80
doc/src/Howto_thermostat.rst
View File

@ -2,8 +2,8 @@ Thermostats
===========
Thermostatting means controlling the temperature of particles in an MD
simulation. :doc:`Barostatting <Howto_barostat>` means controlling the
pressure. Since the pressure includes a kinetic component due to
simulation. :doc:`Barostatting <Howto_barostat>` means controlling
the pressure. Since the pressure includes a kinetic component due to
particle velocities, both these operations require calculation of the
temperature. Typically a target temperature (T) and/or pressure (P)
is specified by the user, and the thermostat or barostat attempts to
@ -26,11 +26,13 @@ can be invoked via the *dpd/tstat* pair style:
* :doc:`pair_style dpd/tstat <pair_dpd>`
:doc:`Fix nvt <fix_nh>` only thermostats the translational velocity of
particles. :doc:`Fix nvt/sllod <fix_nvt_sllod>` also does this, except
that it subtracts out a velocity bias due to a deforming box and
integrates the SLLOD equations of motion. See the :doc:`Howto nemd <Howto_nemd>` page for further details. :doc:`Fix nvt/sphere <fix_nvt_sphere>` and :doc:`fix nvt/asphere <fix_nvt_asphere>` thermostat not only translation
velocities but also rotational velocities for spherical and aspherical
particles.
particles. :doc:`Fix nvt/sllod <fix_nvt_sllod>` also does this,
except that it subtracts out a velocity bias due to a deforming box
and integrates the SLLOD equations of motion. See the :doc:`Howto
nemd <Howto_nemd>` page for further details. :doc:`Fix nvt/sphere
<fix_nvt_sphere>` and :doc:`fix nvt/asphere <fix_nvt_asphere>`
thermostat not only translation velocities but also rotational
velocities for spherical and aspherical particles.
.. note::
@ -40,25 +42,31 @@ particles.
e.g. molecular systems. The latter can be tricky to do correctly.
DPD thermostatting alters pairwise interactions in a manner analogous
to the per-particle thermostatting of :doc:`fix langevin <fix_langevin>`.
to the per-particle thermostatting of :doc:`fix langevin
<fix_langevin>`.
Any of the thermostatting fixes can be instructed to use custom temperature
computes that remove bias which has two effects: first, the current
calculated temperature, which is compared to the requested target temperature,
is calculated with the velocity bias removed; second, the thermostat adjusts
only the thermal temperature component of the particle's velocities, which are
the velocities with the bias removed. The removed bias is then added back
to the adjusted velocities. See the doc pages for the individual
fixes and for the :doc:`fix_modify <fix_modify>` command for
instructions on how to assign a temperature compute to a
thermostatting fix. For example, you can apply a thermostat to only
the x and z components of velocity by using it in conjunction with
:doc:`compute temp/partial <compute_temp_partial>`. Of you could
thermostat only the thermal temperature of a streaming flow of
particles without affecting the streaming velocity, by using
:doc:`compute temp/profile <compute_temp_profile>`.
Any of the thermostatting fixes can be instructed to use custom
temperature computes that remove bias which has two effects: first,
the current calculated temperature, which is compared to the requested
target temperature, is calculated with the velocity bias removed;
second, the thermostat adjusts only the thermal temperature component
of the particle's velocities, which are the velocities with the bias
removed. The removed bias is then added back to the adjusted
velocities. See the doc pages for the individual fixes and for the
:doc:`fix_modify <fix_modify>` command for instructions on how to
assign a temperature compute to a thermostatting fix.
Below is a list of some custom temperature computes that can be used like that:
For example, you can apply a thermostat only to atoms in a spatial
region by using it in conjunction with :doc:`compute temp/region
<compute_temp_region>`. Or you can apply a thermostat to only the x
and z components of velocity by using it with :doc:`compute
temp/partial <compute_temp_partial>`. Of you could thermostat only
the thermal temperature of a streaming flow of particles without
affecting the streaming velocity, by using :doc:`compute temp/profile
<compute_temp_profile>`.
Below is a list of custom temperature computes that can be used like
that:
* :doc:`compute_temp_asphere`
* :doc:`compute_temp_body`
@ -72,8 +80,6 @@ Below is a list of some custom temperature computes that can be used like that:
* :doc:`compute_temp_rotate`
* :doc:`compute_temp_sphere`
.. note::
Only the nvt fixes perform time integration, meaning they update
@ -86,17 +92,17 @@ Below is a list of some custom temperature computes that can be used like that:
* :doc:`fix nve/sphere <fix_nve_sphere>`
* :doc:`fix nve/asphere <fix_nve_asphere>`
Thermodynamic output, which can be setup via the
:doc:`thermo_style <thermo_style>` command, often includes temperature
values. As explained on the page for the
:doc:`thermo_style <thermo_style>` command, the default temperature is
setup by the thermo command itself. It is NOT the temperature
associated with any thermostatting fix you have defined or with any
compute you have defined that calculates a temperature. The doc pages
for the thermostatting fixes explain the ID of the temperature compute
they create. Thus if you want to view these temperatures, you need to
specify them explicitly via the :doc:`thermo_style custom <thermo_style>` command. Or you can use the
:doc:`thermo_modify <thermo_modify>` command to re-define what
Thermodynamic output, which can be setup via the :doc:`thermo_style
<thermo_style>` command, often includes temperature values. As
explained on the page for the :doc:`thermo_style <thermo_style>`
command, the default temperature is setup by the thermo command
itself. It is NOT the temperature associated with any thermostatting
fix you have defined or with any compute you have defined that
calculates a temperature. The doc pages for the thermostatting fixes
explain the ID of the temperature compute they create. Thus if you
want to view these temperatures, you need to specify them explicitly
via the :doc:`thermo_style custom <thermo_style>` command. Or you can
use the :doc:`thermo_modify <thermo_modify>` command to re-define what
temperature compute is used for default thermodynamic output.
----------

47
doc/src/Install_git.rst
View File

@ -9,7 +9,8 @@ has several advantages:
command.
* You can create your own development branches to add code to LAMMPS.
* You can submit your new features back to GitHub for inclusion in
LAMMPS.
LAMMPS. For that you should first create your own :doc:`fork on
GitHub <Howto_github>`.
You must have `git <git_>`_ installed on your system to use the
commands explained below to communicate with the git servers on
@ -20,35 +21,53 @@ provides `limited support for subversion clients <svn_>`_.
As of October 2016, the official home of public LAMMPS development is
on GitHub. The previously advertised LAMMPS git repositories on
git.lammps.org and bitbucket.org are now deprecated or offline.
git.lammps.org and bitbucket.org are now offline or deprecated.
.. _git: https://git-scm.com
.. _svn: https://help.github.com/en/github/importing-your-projects-to-github/working-with-subversion-on-github
You can follow LAMMPS development on 3 different git branches:
You can follow the LAMMPS development on 3 different git branches:
* **stable** : this branch is updated with every stable release
* **unstable** : this branch is updated with every patch release
* **master** : this branch continuously follows ongoing development
* **stable** : this branch is updated with every stable release;
updates are always "fast forward" merges from *develop*
* **release** : this branch is updated with every patch release;
updates are always "fast forward" merges from *develop*
* **develop** : this branch follows the ongoing development and
is updated with every merge commit of a pull request
To access the git repositories on your box, use the clone command to
create a local copy of the LAMMPS repository with a command like:
.. code-block:: bash
$ git clone -b unstable https://github.com/lammps/lammps.git mylammps
$ git clone -b release https://github.com/lammps/lammps.git mylammps
where "mylammps" is the name of the directory you wish to create on
your machine and "unstable" is one of the 3 branches listed above.
your machine and "release" is one of the 3 branches listed above.
(Note that you actually download all 3 branches; you can switch
between them at any time using "git checkout <branch name>".)
.. note::
The complete git history of the LAMMPS project is quite large because
it contains the entire commit history of the project since fall 2006,
which includes the time when LAMMPS was managed with subversion. This
also includes commits that have added and removed some large files
(mostly by accident). If you do not need access to the entire commit
history, you can speed up the "cloning" process and reduce local disk
space requirements by using the *--depth* git command line flag thus
create a "shallow clone" of the repository that contains only a
subset of the git history. Using a depth of 1000 is usually sufficient
to include the head commits of the *develop* and the *release* branches.
To include the head commit of the *stable* branch you may need a depth
of up to 10000.
Once the command completes, your directory will contain the same files
as if you unpacked a current LAMMPS tarball, with the exception, that
the HTML documentation files are not included. They can be fetched
from the LAMMPS website by typing ``make fetch`` in the doc directory.
Or they can be generated from the content provided in doc/src by
typing ``make html`` from the doc directory.
Or they can be generated from the content provided in ``doc/src`` by
typing ``make html`` from the ``doc`` directory.
After initial cloning, as bug fixes and new features are added to
LAMMPS you can stay up-to-date by typing the following git commands
@ -56,9 +75,9 @@ from within the "mylammps" directory:
.. code-block:: bash
$ git checkout unstable # not needed if you always stay in this branch
$ git checkout stable # use one of these 3 checkout commands
$ git checkout master # to choose the branch to follow
$ git checkout release # not needed if you always stay in this branch
$ git checkout stable # use one of these 3 checkout commands
$ git checkout develop # to choose the branch to follow
$ git pull
Doing a "pull" will not change any files you have added to the LAMMPS
@ -81,7 +100,7 @@ Stable versions and what tagID to use for a particular stable version
are discussed on `this page <https://www.lammps.org/bug.html#version>`_.
Note that this command will print some warnings, because in order to get
back to the latest revision and to be able to update with ``git pull``
again, you will need to do ``git checkout unstable`` (or
again, you will need to do ``git checkout release`` (or
check out any other desired branch) first.
Once you have updated your local files with a ``git pull`` (or ``git

2
doc/src/Install_windows.rst
View File

@ -12,7 +12,7 @@ Note that each installer package has a date in its name, which
corresponds to the LAMMPS version of the same date. Installers for
current and older versions of LAMMPS are available. 32-bit and 64-bit
installers are available, and each installer contains both a serial
and parallel executable. The installer web site also explains how to
and parallel executable. The installer website also explains how to
install the Windows MPI package (MPICH2 from Argonne National Labs),
needed to run in parallel with MPI.

5
doc/src/Intro_authors.rst
View File

@ -29,7 +29,7 @@ The following folks deserve special recognition. Many of the packages
they have written are unique for an MD code and LAMMPS would not be as
general-purpose as it is without their expertise and efforts.
* Metin Aktulga (MSU), REAXFF package for C version of ReaxFF
* Metin Aktulga (MSU), REAXFF package for C/C++ version of ReaxFF
* Mike Brown (Intel), GPU and INTEL packages
* Colin Denniston (U Western Ontario), LATBOLTZ package
* Georg Ganzenmuller (EMI), MACHDYN and SPH packages
@ -37,9 +37,10 @@ general-purpose as it is without their expertise and efforts.
* Reese Jones (Sandia) and colleagues, ATC package for atom/continuum coupling
* Christoph Kloss (DCS Computing), LIGGGHTS code for granular materials, built on top of LAMMPS
* Rudra Mukherjee (JPL), POEMS package for articulated rigid body motion
* Trung Ngyuen (Northwestern U), GPU and RIGID and BODY packages
* Trung Ngyuen (Northwestern U), GPU, RIGID, BODY, and DIELECTRIC packages
* Mike Parks (Sandia), PERI package for Peridynamics
* Roy Pollock (LLNL), Ewald and PPPM solvers
* Julien Tranchida (Sandia), SPIN package
* Christian Trott (Sandia), CUDA and KOKKOS packages
* Ilya Valuev (JIHT), AWPMD package for wave packet MD
* Greg Wagner (Northwestern U), MEAM package for MEAM potential

59
doc/src/Intro_citing.rst
View File

@ -4,28 +4,41 @@ Citing LAMMPS
Core Algorithms
^^^^^^^^^^^^^^^
Since LAMMPS is a community project, there is not a single one
publication or reference that describes **all** of LAMMPS.
The canonical publication that describes the foundation, that is
the basic spatial decomposition approach, the neighbor finding,
and basic communications algorithms used in LAMMPS is:
The paper mentioned below is the best overview of LAMMPS, but there are
also publications describing particular models or algorithms implemented
in LAMMPS or complementary software that is has interfaces to. Please
see below for how to cite contributions to LAMMPS.
`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>`_
.. _lammps_paper:
So any project using LAMMPS (or a derivative application using LAMMPS as
a simulation engine) should cite this paper. A new publication
describing the developments and improvements of LAMMPS in the 25 years
since then is currently in preparation.
The latest canonical publication that describes the basic features, the
source code design, the program structure, the spatial decomposition
approach, the neighbor finding, basic communications algorithms, and how
users and developers have contributed to LAMMPS is:
`LAMMPS - A flexible simulation tool for particle-based materials modeling at the atomic, meso, and continuum scales, Comp. Phys. Comm. (accepted 09/2021), DOI:10.1016/j.cpc.2021.108171 <https://doi.org/10.1016/j.cpc.2021.108171>`_
So a project using LAMMPS or a derivative application that uses LAMMPS
as a simulation engine should cite this paper. The paper is expected to
be published in its final form under the same DOI in the first half
of 2022. Please also give the URL of the LAMMPS website in your paper,
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>`_
DOI for the LAMMPS code
^^^^^^^^^^^^^^^^^^^^^^^
LAMMPS developers use the `Zenodo service at CERN
<https://zenodo.org/>`_ to create digital object identifies (DOI) for
stable releases of the LAMMPS code. There are two types of DOIs for the
LAMMPS source code: the canonical DOI for **all** versions of LAMMPS,
which will always point to the **latest** stable release version is:
LAMMPS developers use the `Zenodo service at CERN <https://zenodo.org/>`_
to create digital object identifies (DOI) for stable releases of the
LAMMPS source code. There are two types of DOIs for the LAMMPS source code.
The canonical DOI for **all** versions of LAMMPS, which will always
point to the **latest** stable release version is:
- DOI: `10.5281/zenodo.3726416 <https://dx.doi.org/10.5281/zenodo.3726416>`_
@ -45,11 +58,13 @@ about LAMMPS and its features.
Citing contributions
^^^^^^^^^^^^^^^^^^^^
LAMMPS has many features and that use either previously published
methods and algorithms or novel features. It also includes potential
parameter filed for specific models. Where available, a reminder about
references for optional features used in a specific run is printed to
the screen and log file. Style and output location can be selected with
the :ref:`-cite command-line switch <cite>`. Additional references are
LAMMPS has many features that use either previously published methods
and algorithms or novel features. It also includes potential parameter
files for specific models. Where available, a reminder about references
for optional features used in a specific run is printed to the screen
and log file. Style and output location can be selected with the
:ref:`-cite command-line switch <cite>`. Additional references are
given in the documentation of the :doc:`corresponding commands
<Commands_all>` or in the :doc:`Howto tutorials <Howto>`.
<Commands_all>` or in the :doc:`Howto tutorials <Howto>`. So please
make certain, that you provide the proper acknowledgments and citations
in any published works using LAMMPS.

58
doc/src/Intro_features.rst
View File

@ -27,19 +27,19 @@ General features
* distributed memory message-passing parallelism (MPI)
* shared memory multi-threading parallelism (OpenMP)
* spatial decomposition of simulation domain for MPI parallelism
* particle decomposition inside of spatial decomposition for OpenMP parallelism
* particle decomposition inside of spatial decomposition for OpenMP and GPU parallelism
* GPLv2 licensed open-source distribution
* highly portable C++-11
* modular code with most functionality in optional packages
* only depends on MPI library for basic parallel functionality
* only depends on MPI library for basic parallel functionality, MPI stub for serial compilation
* other libraries are optional and only required for specific packages
* GPU (CUDA and OpenCL), Intel Xeon Phi, and OpenMP support for many code features
* GPU (CUDA, OpenCL, HIP, SYCL), Intel Xeon Phi, and OpenMP support for many code features
* easy to extend with new features and functionality
* runs from an input script
* syntax for defining and using variables and formulas
* syntax for looping over runs and breaking out of loops
* run one or multiple simulations simultaneously (in parallel) from one script
* build as library, invoke LAMMPS through library interface or provided Python wrapper
* build as library, invoke LAMMPS through library interface or provided Python wrapper or SWIG based wrappers
* couple with other codes: LAMMPS calls other code, other code calls LAMMPS, umbrella code calls both
.. _particle:
@ -57,9 +57,11 @@ Particle and model types
* granular materials
* coarse-grained mesoscale models
* finite-size spherical and ellipsoidal particles
* finite-size line segment (2d) and triangle (3d) particles
* finite-size line segment (2d) and triangle (3d) particles
* finite-size rounded polygons (2d) and polyhedra (3d) particles
* point dipole particles
* rigid collections of particles
* particles with magnetic spin
* rigid collections of n particles
* hybrid combinations of these
.. _ff:
@ -74,24 +76,28 @@ commands)
* pairwise potentials: Lennard-Jones, Buckingham, Morse, Born-Mayer-Huggins, Yukawa, soft, class 2 (COMPASS), hydrogen bond, tabulated
* charged pairwise potentials: Coulombic, point-dipole
* many-body potentials: EAM, Finnis/Sinclair EAM, modified EAM (MEAM), embedded ion method (EIM), EDIP, ADP, Stillinger-Weber, Tersoff, REBO, AIREBO, ReaxFF, COMB, SNAP, Streitz-Mintmire, 3-body polymorphic
* long-range interactions for charge, point-dipoles, and LJ dispersion: Ewald, Wolf, PPPM (similar to particle-mesh Ewald)
* many-body potentials: EAM, Finnis/Sinclair EAM, modified EAM (MEAM), embedded ion method (EIM), EDIP, ADP, Stillinger-Weber, Tersoff, REBO, AIREBO, ReaxFF, COMB, Streitz-Mintmire, 3-body polymorphic, BOP, Vashishta
* machine learning potentials: SNAP, GAP, ACE, N2P2, RANN, AGNI
* long-range interactions for charge, point-dipoles, and LJ dispersion: Ewald, Wolf, PPPM (similar to particle-mesh Ewald), MSM
* polarization models: :doc:`QEq <fix_qeq>`, :doc:`core/shell model <Howto_coreshell>`, :doc:`Drude dipole model <Howto_drude>`
* charge equilibration (QEq via dynamic, point, shielded, Slater methods)
* coarse-grained potentials: DPD, GayBerne, REsquared, colloidal, DLVO
* mesoscopic potentials: granular, Peridynamics, SPH
* mesoscopic potentials: granular, Peridynamics, SPH, mesoscopic tubular potential (MESONT)
* semi-empirical potentials: multi-ion generalized pseudopotential theory (MGPT), second moment tight binding + QEq (SMTB-Q), density functional tight-binding (LATTE)
* electron force field (eFF, AWPMD)
* bond potentials: harmonic, FENE, Morse, nonlinear, class 2, quartic (breakable)
* angle potentials: harmonic, CHARMM, cosine, cosine/squared, cosine/periodic, class 2 (COMPASS)
* dihedral potentials: harmonic, CHARMM, multi-harmonic, helix, class 2 (COMPASS), OPLS
* improper potentials: harmonic, cvff, umbrella, class 2 (COMPASS)
* bond potentials: harmonic, FENE, Morse, nonlinear, class 2, quartic (breakable), tabulated
* angle potentials: harmonic, CHARMM, cosine, cosine/squared, cosine/periodic, class 2 (COMPASS), tabulated
* dihedral potentials: harmonic, CHARMM, multi-harmonic, helix, class 2 (COMPASS), OPLS, tabulated
* improper potentials: harmonic, cvff, umbrella, class 2 (COMPASS), tabulated
* polymer potentials: all-atom, united-atom, bead-spring, breakable
* water potentials: TIP3P, TIP4P, SPC
* water potentials: TIP3P, TIP4P, SPC, SPC/E and variants
* interlayer potentials for graphene and analogues
* 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
* 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>`
* hybrid potentials: multiple pair, bond, angle, dihedral, improper potentials can be used in one simulation
* overlaid potentials: superposition of multiple pair potentials
* 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
.. _create:
@ -124,9 +130,10 @@ Ensembles, constraints, and boundary conditions
* harmonic (umbrella) constraint forces
* rigid body constraints
* SHAKE bond and angle constraints
* Monte Carlo bond breaking, formation, swapping
* motion constraints to manifold surfaces
* Monte Carlo bond breaking, formation, swapping, template based reaction modeling
* atom/molecule insertion and deletion
* walls of various kinds
* walls of various kinds, static and moving
* non-equilibrium molecular dynamics (NEMD)
* variety of additional boundary conditions and constraints
@ -150,6 +157,7 @@ Diagnostics
^^^^^^^^^^^
* see various flavors of the :doc:`fix <fix>` and :doc:`compute <compute>` commands
* introspection command for system, simulation, and compile time settings and configurations
.. _output:
@ -164,8 +172,9 @@ Output
* parallel I/O of dump and restart files
* per-atom quantities (energy, stress, centro-symmetry parameter, CNA, etc)
* user-defined system-wide (log file) or per-atom (dump file) calculations
* spatial and time averaging of per-atom quantities
* time averaging of system-wide quantities
* custom partitioning (chunks) for binning, and static or dynamic grouping of atoms for analysis
* spatial, time, and per-chunk averaging of per-atom quantities
* time averaging and histogramming of system-wide quantities
* atom snapshots in native, XYZ, XTC, DCD, CFG formats
.. _replica1:
@ -178,7 +187,7 @@ Multi-replica models
* :doc:`parallel replica dynamics <prd>`
* :doc:`temperature accelerated dynamics <tad>`
* :doc:`parallel tempering <temper>`
* :doc:`path-integral MD <fix_pimd>`
* path-integral MD: `first variant <fix_pimd>`, `second variant <fix_ipi>`
* multi-walker collective variables with :doc:`Colvars <fix_colvars>` and :doc:`Plumed <fix_plumed>`
.. _prepost:
@ -210,11 +219,12 @@ page for details.
These are LAMMPS capabilities which you may not think of as typical
classical MD options:
* :doc:`static <balance>` and :doc:`dynamic load-balancing <fix_balance>`
* :doc:`static <balance>` and :doc:`dynamic load-balancing <fix_balance>`, optional with recursive bisectioning decomposition
* :doc:`generalized aspherical particles <Howto_body>`
* :doc:`stochastic rotation dynamics (SRD) <fix_srd>`
* :doc:`real-time visualization and interactive MD <fix_imd>`
* :doc:`real-time visualization and interactive MD <fix_imd>`, :doc:`built-in renderer for images and movies <dump_image>`
* calculate :doc:`virtual diffraction patterns <compute_xrd>`
* calculate :doc:`finite temperature phonon dispersion <fix_phonon>` and the :doc:`dynamical matrix of minimized structures <dynamical_matrix>`
* :doc:`atom-to-continuum coupling <fix_atc>` with finite elements
* coupled rigid body integration via the :doc:`POEMS <fix_poems>` library
* :doc:`QM/MM coupling <fix_qmmm>`

57
doc/src/Intro_opensource.rst
View File

@ -1,40 +1,61 @@
LAMMPS open-source license
--------------------------
LAMMPS is a freely-available open-source code, distributed under the
terms of the `GNU Public License Version 2 <gpl_>`_, which means you can
use or modify the code however you wish for your own purposes, but have
to adhere to certain rules when redistributing it or software derived
GPL version of LAMMPS
^^^^^^^^^^^^^^^^^^^^^
LAMMPS is an open-source code, available free-of-charge, and distributed
under the terms of the `GNU Public License Version 2 <gpl_>`_ (GPLv2),
which means you can use or modify the code however you wish for your own
purposes, but have to adhere to certain rules when redistributing it -
specifically in binary form - or are distributing software derived
from it or that includes parts of it.
LAMMPS comes with no warranty of any kind. As each source file states
in its header, it is a copyrighted code that is distributed free-of-
charge, under the terms of the `GNU Public License Version 2 <gpl_>`_
(GPLv2). This is often referred to as open-source distribution - see
`www.gnu.org <gnuorg_>`_ or `www.opensource.org <opensource_>`_. The
legal text of the GPL is in the LICENSE file included in the LAMMPS
distribution.
LAMMPS comes with no warranty of any kind.
.. _gpl: https://github.com/lammps/lammps/blob/master/LICENSE
As each source file states in its header, it is a copyrighted code, and
thus not in the public domain. For more information about open-source
software and open-source distribution, see `www.gnu.org <gnuorg_>`_
or `www.opensource.org <opensource_>`_. The legal text of the GPL as it
applies to LAMMPS is in the LICENSE file included in the LAMMPS distribution.
.. _gpl: https://github.com/lammps/lammps/blob/develop/LICENSE
.. _lgpl: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html
.. _gnuorg: http://www.gnu.org
.. _opensource: http://www.opensource.org
Here is a summary of what the GPL means for LAMMPS users:
Here is a more specific summary of what the GPL means for LAMMPS users:
(1) Anyone is free to use, modify, or extend LAMMPS in any way they
(1) Anyone is free to use, copy, modify, or extend LAMMPS in any way they
choose, including for commercial purposes.
(2) If you **distribute** a modified version of LAMMPS, it must remain
open-source, meaning you distribute **all** of it under the terms of
the GPL. You should clearly annotate such a code as a derivative version
of LAMMPS.
open-source, meaning you are required to distribute **all** of it under
the terms of the GPL. You should clearly annotate such a modified code
as a derivative version of LAMMPS.
(3) If you release any code that includes or uses LAMMPS source code,
then it must also be open-sourced, meaning you distribute it under
the terms of the GPL.
the terms of the GPL. You may write code that interfaces LAMMPS to
a differently licensed library. In that case the code that provides
the interface must be licensed GPL, but not necessarily that library
unless you are distributing binaries that require the library to run.
(4) If you give LAMMPS files to someone else, the GPL LICENSE file and
source file headers (including the copyright and GPL notices) should
remain part of the code.
LGPL version of LAMMPS
^^^^^^^^^^^^^^^^^^^^^^
We occasionally make stable LAMMPS releases available under the `GNU
Lesser Public License v2.1 <lgpl_>`_. This is on request only and with
non-LGPL compliant files removed. This allows uses linking non-GPL
compatible software with the (otherwise unmodified) LAMMPS library
or loading it dynamically at runtime. Any **modifications** to
the LAMMPS code however, even with the LGPL licensed version, must still
be made available under the same open source terms as LAMMPS itself.

27
doc/src/Intro_overview.rst
View File

@ -10,24 +10,26 @@ conditions. It can model 2d or 3d systems with only a few particles
up to millions or billions.
LAMMPS can be built and run on a laptop or desktop machine, but is
designed for parallel computers. It will run on any parallel machine
that supports the `MPI <mpi_>`_ message-passing library. This includes
shared-memory boxes and distributed-memory clusters and
supercomputers.
designed for parallel computers. It will run in serial and on any
parallel machine that supports the `MPI <mpi_>`_ message-passing
library. This includes shared-memory boxes and distributed-memory
clusters and supercomputers. Parts of LAMMPS also support
`OpenMP multi-threading <omp_>`_, vectorization and GPU acceleration.
.. _mpi: https://en.wikipedia.org/wiki/Message_Passing_Interface
.. _lws: https://www.lammps.org
.. _omp: https://www.openmp.org
LAMMPS is written in C++ and requires a compiler that is at least
compatible with the C++-11 standard.
Earlier versions were written in F77 and F90. See the `History page
compatible with the C++-11 standard. Earlier versions were written in
F77, F90, and C++-98. See the `History page
<https://www.lammps.org/history.html>`_ of the website for details. All
versions can be downloaded from the `LAMMPS website <lws_>`_.
versions can be downloaded as source code from the `LAMMPS website
<lws_>`_.
LAMMPS is designed to be easy to modify or extend with new
capabilities, such as new force fields, atom types, boundary
conditions, or diagnostics. See the :doc:`Modify <Modify>` page for
more details.
LAMMPS is designed to be easy to modify or extend with new capabilities,
such as new force fields, atom types, boundary conditions, or
diagnostics. See the :doc:`Modify <Modify>` page for more details.
In the most general sense, LAMMPS integrates Newton's equations of
motion for a collection of interacting particles. A single particle
@ -47,4 +49,5 @@ MPI parallelization to partition the simulation domain into small
sub-domains of equal computational cost, one of which is assigned to
each processor. Processors communicate and store "ghost" atom
information for atoms that border their sub-domain. Multi-threading
parallelization with with particle-decomposition can be used in addition.
parallelization and GPU acceleration with with particle-decomposition
can be used in addition.

2
doc/src/Intro_website.rst
View File

@ -26,7 +26,7 @@ available online are listed below.
* `Tutorials <https://www.lammps.org/tutorials.html>`_
* `Pre- and post-processing tools for LAMMPS <https://www.lammps.org/prepost.html>`_
* `Other software usable with LAMMPS <https://www.lammps.org/offsite.html>`_
* `Other software usable with LAMMPS <https://www.lammps.org/external.html>`_
* `Viz tools usable with LAMMPS <https://www.lammps.org/viz.html>`_
* `Benchmark performance <https://www.lammps.org/bench.html>`_

13
doc/src/Library_create.rst
View File

@ -10,6 +10,7 @@ This section documents the following functions:
- :cpp:func:`lammps_mpi_init`
- :cpp:func:`lammps_mpi_finalize`
- :cpp:func:`lammps_kokkos_finalize`
- :cpp:func:`lammps_python_finalize`
--------------------
@ -33,7 +34,7 @@ simple example demonstrating its use:
int lmpargc = sizeof(lmpargv)/sizeof(const char *);
/* create LAMMPS instance */
handle = lammps_open_no_mpi(lmpargc, lmpargv, NULL);
handle = lammps_open_no_mpi(lmpargc, (char **)lmpargv, NULL);
if (handle == NULL) {
printf("LAMMPS initialization failed");
lammps_mpi_finalize();
@ -104,3 +105,13 @@ calling program.
.. doxygenfunction:: lammps_mpi_finalize
:project: progguide
-----------------------
.. doxygenfunction:: lammps_kokkos_finalize
:project: progguide
-----------------------
.. doxygenfunction:: lammps_python_finalize
:project: progguide

21
doc/src/Manual_version.rst
View File

@ -2,12 +2,21 @@ What does a LAMMPS version mean
-------------------------------
The LAMMPS "version" is the date when it was released, such as 1 May
2014. LAMMPS is updated continuously. Whenever we fix a bug or add a
feature, we release it in the next *patch* release, which are
typically made every couple of weeks. Info on patch releases are on
`this website page <https://www.lammps.org/bug.html>`_. Every few
months, the latest patch release is subjected to more thorough testing
and labeled as a *stable* version.
2014. LAMMPS is updated continuously and we aim to keep it working
correctly and reliably at all times. You can follow its development
in a public `git repository on GitHub <https://github.com/lammps/lammps>`_.
Whenever we fix a bug or update or add a feature, it will be merged into
the *develop* branch of the git repository. When a sufficient number of
changes have accumulated *and* the software passes a set of automated
tests, we release it in the next *patch* release, which are made every
few weeks. Info on patch releases are on `this website page
<https://www.lammps.org/bug.html>`_.
Once or twice a year, only bug fixes and small, non-intrusive changes are
included for a period of time, and the code is subjected to more detailed
and thorough testing than the default automated testing. The latest
patch release after such a period is then labeled as a *stable* version.
Each version of LAMMPS contains all the features and bug-fixes up to
and including its version date.

4
doc/src/Modify.rst
View File

@ -9,13 +9,15 @@ this.
If you add a new feature to LAMMPS and think it will be of interest to
general users, we encourage you to submit it for inclusion in LAMMPS
as a pull request on our `GitHub site <https://github.com/lammps/lammps>`_,
after reading :doc:`this page <Modify_contribute>`.
after reading about :doc:`how to prepare your code for submission <Modify_contribute>`
and :doc:`the style requirements and recommendations <Modify_style>`.
.. toctree::
:maxdepth: 1
Modify_overview
Modify_contribute
Modify_style
.. toctree::
:maxdepth: 1

336
doc/src/Modify_contribute.rst
View File

@ -1,22 +1,20 @@
Submitting new features for inclusion in LAMMPS
===============================================
We encourage users to submit new features or modifications for LAMMPS to
`the core developers <https://www.lammps.org/authors.html>`_ so they
can be added to the LAMMPS distribution. The preferred way to manage and
coordinate this is via the LAMMPS project on `GitHub
<https://github.com/lammps/lammps>`_. Please see the :doc:`GitHub
Tutorial <Howto_github>` for a demonstration on how to do that. An
alternative is to contact the LAMMPS developers or the indicated
developer of a package or feature directly and send in your contribution
via e-mail, but that can add a significant delay on getting your
contribution included, depending on how busy the respective developer
is, how complex a task it would be to integrate that code, and how
many - if any - changes are required before the code can be included.
We encourage LAMMPS users to submit new features they wrote for LAMMPS
to be included into the LAMMPS distribution and thus become easily
accessible to all LAMMPS users. The LAMMPS source code is managed with
git and public development is hosted on `GitHub
<https://github.com/lammps/lammps>`_. You can monitor the repository to
be notified of releases, follow the ongoing development, and comment on
topics of interest to you.
Communication with the LAMMPS developers
----------------------------------------
For any larger modifications or programming project, you are encouraged
to contact the LAMMPS developers ahead of time in order to discuss
implementation strategies and coding guidelines. That will make it
implementation strategies and coding guidelines. That will make it
easier to integrate your contribution and results in less work for
everybody involved. You are also encouraged to search through the list
of `open issues on GitHub <https://github.com/lammps/lammps/issues>`_
@ -24,235 +22,105 @@ and submit a new issue for a planned feature, so you would not duplicate
the work of others (and possibly get scooped by them) or have your work
duplicated by others.
For informal communication with (some of) the LAMMPS developers you may
ask to join the `LAMMPS developers on Slack
<https://lammps.slack.com>`_. This slack work space is by invitation
only. Thus for access, please send an e-mail to ``slack@lammps.org``
explaining what part of LAMMPS you are working on. Only discussions
related to LAMMPS development are tolerated, so this is **NOT** for
people that look for help with compiling, installing, or using
LAMMPS. Please contact the
`lammps-users mailing list <https://www.lammps.org/mail.html>`_ or the
`LAMMPS forum <https://www.lammps.org/forum.html>`_ for those purposes
instead.
For informal communication with the LAMMPS developers you may ask to
join the `LAMMPS developers on Slack <https://lammps.slack.com>`_. This
slack work space is by invitation only. Thus for access, please send an
e-mail to ``slack@lammps.org`` explaining what part of LAMMPS you are
working on. Only discussions related to LAMMPS development are
tolerated in that work space, so this is **NOT** for people that look for
help with compiling, installing, or using LAMMPS. Please post a message
to the `lammps-users mailing list <https://www.lammps.org/mail.html>`_
or the `LAMMPS forum <https://www.lammps.org/forum.html>`_ for those
purposes.
How quickly your contribution will be integrated depends largely on how
much effort it will cause to integrate and test it, how many and what
kind of changes it requires to the core codebase, and of how much
interest it is to the larger LAMMPS community. Please see below for a
checklist of typical requirements. Once you have prepared everything,
see the :doc:`LAMMPS GitHub Tutorial <Howto_github>` page for
instructions on how to submit your changes or new files through a GitHub
pull request. If you prefer to submit patches or full files, you should
first make certain, that your code works correctly with the latest
patch-level version of LAMMPS and contains all bug fixes from it. Then
create a gzipped tar file of all changed or added files or a
corresponding patch file using 'diff -u' or 'diff -c' and compress it
with gzip. Please only use gzip compression, as this works well and is
available on all platforms.
Packages versus individual files
--------------------------------
The remainder of this chapter describes how to add new "style" files of
various kinds to LAMMPS. Packages are simply collections of one or more
such new class files which are invoked as a new style within a LAMMPS
input script. In some cases also collections of supporting functions or
classes are included as separate files in a package, especially when
they can be shared between multiple styles. If designed correctly, these
additions typically do not require any changes to the core code of
LAMMPS; they are simply add-on files that are compiled with the rest of
LAMMPS. To make those styles work, you may need some trivial changes to
the core code; an example of a trivial change is making a parent-class
method "virtual" when you derive a new child class from it.
If you think your new feature or package requires some non-trivial
changes in core LAMMPS files, you should communicate with the LAMMPS
developers `on Slack <https://lammps.org/slack.html>`_, `on GitHub
<https://github.com/lammps/lammps/issues>`_, or `via email
<https://www.lammps.org/authors.html>`_, since we may have
recommendations about what changes to do where, or may not want to
include certain changes for some reason and thus you would need to look
for alternatives.
Time and effort required
------------------------
How quickly your contribution will be integrated can vary a lot. It
depends largely on how much effort it will cause the LAMMPS developers
to integrate and test it, how many and what kind of changes to the core
code are required, how quickly you can address them and of how much
interest it is to the larger LAMMPS community. Please see the section
on :doc:`LAMMPS programming style and requirements <Modify_style>` for
instructions, recommendations, and formal requirements. A small,
modular, well written contribution may be integrated within hours, but a
complex change that will require a redesign of some core functionality
in LAMMPS for a clean integration can take many months until it is
considered ready for inclusion (though this is rare).
Submission procedure
--------------------
All changes to LAMMPS (including those from LAMMPS developers) are
integrated via pull requests on GitHub and cannot be merged without
passing the automated testing and an approving review by a LAMMPS core
developer. Thus before submitting your contribution, you should first
make certain, that your added or modified code compiles and works
correctly with the latest patch-level or development version of LAMMPS
and contains all bug fixes from it.
Once you have prepared everything, see the :doc:`LAMMPS GitHub Tutorial
<Howto_github>` page for instructions on how to submit your changes or
new files through a GitHub pull request yourself. If you are unable or
unwilling to submit via GitHub yourself, you may also submit patch files
or full files to the LAMMPS developers and ask them to submit a pull
request on GitHub on your behalf. Then create a gzipped tar file of
all changed or added files or a corresponding patch file using
'diff -u' or 'diff -c' format and compress it with gzip. Please only
use gzip compression, as this works well and is available on all platforms.
If the new features/files are broadly useful we may add them as core
files to LAMMPS or as part of a :doc:`package <Packages_list>`. All
packages are listed and described on the :doc:`Packages details
<Packages_details>` doc page.
Note that by providing us files to release, you are agreeing to make
them open-source, i.e. we can release them under the terms of the GPL
(version 2), used as a license for the rest of LAMMPS. And as part of
a LGPL (version 2.1) distribution that we make available to developers
on request only and with files that are authorized for that kind of
distribution removed (e.g. interface to FFTW). See the
Licensing
---------
Note that by providing us files to release, you agree to make them
open-source, i.e. we can release them under the terms of the GPL
(version 2) with the rest of LAMMPS. And similarly as part of a LGPL
(version 2.1) distribution of LAMMPS that we make available to
developers on request only and with files that are not authorized for
that kind of distribution removed (e.g. interface to FFTW). See the
:doc:`LAMMPS license <Intro_opensource>` page for details.
.. note::
External contributions
----------------------
If you prefer to actively develop and support your add-on feature
yourself, then you may wish to make it available for download from
your own website, as a user package that LAMMPS users can add to
their copy of LAMMPS. See the `Offsite LAMMPS packages and tools
<https://www.lammps.org/offsite.html>`_ page of the LAMMPS web site
for examples of groups that do this. We are happy to advertise your
package and web site from that page. Simply email the `developers
<https://www.lammps.org/authors.html>`_ with info about your package
and we will post it there. We recommend to name external packages
USER-\<name\> so they can be easily distinguished from bundled packages
that do not have the USER- prefix.
If you prefer to do so, you can also develop and support your add-on
feature **without** having it included in the LAMMPS distribution, for
example as a download from a website of your own. See the `External
LAMMPS packages and tools <https://www.lammps.org/external.html>`_ page
of the LAMMPS website for examples of groups that do this. We are happy
to advertise your package and website from that page. Simply email the
`developers <https://www.lammps.org/authors.html>`_ with info about your
package and we will post it there. We recommend to name external
packages USER-\<name\> so they can be easily distinguished from bundled
packages that do not have the USER- prefix.
.. _lws: https://www.lammps.org
The previous sections of this page describe how to add new "style"
files of various kinds to LAMMPS. Packages are simply collections of
one or more new class files which are invoked as a new style within a
LAMMPS input script. If designed correctly, these additions typically
do not require changes to the main core of LAMMPS; they are simply
add-on files. If you think your new feature requires non-trivial
changes in core LAMMPS files, you should `communicate with the
developers <https://www.lammps.org/authors.html>`_, since we may or
may not want to include those changes for some reason. An example of a
trivial change is making a parent-class method "virtual" when you derive
a new child class from it.
Here is a checklist of steps you need to follow to submit a single file
or package for our consideration. Following these steps will save
both you and us time. Please have a look at the existing files in
packages in the src directory for examples. If you are uncertain, please ask.
* All source files you provide must compile with the most current
version of LAMMPS with multiple configurations. In particular you
need to test compiling LAMMPS from scratch with -DLAMMPS_BIGBIG
set in addition to the default -DLAMMPS_SMALLBIG setting. Your code
will need to work correctly in serial and in parallel using MPI.
* For consistency with the rest of LAMMPS and especially, if you want
your contribution(s) to be added to main LAMMPS code or one of its
standard packages, it needs to be written in a style compatible with
other LAMMPS source files. This means: 2-character indentation per
level, **no tabs**, no lines over 100 characters. I/O is done via
the C-style stdio library (mixing of stdio and iostreams is generally
discouraged), class header files should not import any system headers
outside of <cstdio>, STL containers should be avoided in headers,
system header from the C library should use the C++-style names
(<cstdlib>, <cstdio>, or <cstring>) instead of the C-style names
<stdlib.h>, <stdio.h>, or <string.h>), and forward declarations
used where possible or needed to avoid including headers.
All added code should be placed into the LAMMPS_NS namespace or a
sub-namespace; global or static variables should be avoided, as they
conflict with the modular nature of LAMMPS and the C++ class structure.
Header files must **not** import namespaces with *using*\ .
This all is so the developers can more easily understand, integrate,
and maintain your contribution and reduce conflicts with other parts
of LAMMPS. This basically means that the code accesses data
structures, performs its operations, and is formatted similar to other
LAMMPS source files, including the use of the error class for error
and warning messages.
* To simplify reformatting contributed code in a way that is compatible
with the LAMMPS formatting styles, you can use clang-format (version 8
or later). The LAMMPS distribution includes a suitable ``.clang-format``
file which will be applied if you run ``clang-format -i some_file.cpp``
on your files inside the LAMMPS src tree. Please only reformat files
that you have contributed. For header files containing a
``SomeStyle(keyword, ClassName)`` macros it is required to have this
macro embedded with a pair of ``// clang-format off``, ``// clang-format on``
commends and the line must be terminated with a semi-colon (;).
Example:
.. code-block:: c++
#ifdef COMMAND_CLASS
// clang-format off
CommandStyle(run,Run);
// clang-format on
#else
#ifndef LMP_RUN_H
[...]
You may also use ``// clang-format on/off`` throughout your file
to protect sections of the file from being reformatted.
* Please review the list of :doc:`available Packages <Packages_details>`
to see if your contribution could be added to be added to one of them.
It should fit into the general purposed of that package. If it does not
fit well, it can be added to one of the EXTRA- packages or the MISC package.
* If your contribution has several related features that are not covered
by one of the existing packages or is dependent on a library (bundled
or external), it is best to make it a package directory with a name
like FOO. In addition to your new files, the directory should contain
a README text file. The README should contain your name and contact
information and a brief description of what your new package does. If
your files depend on other LAMMPS style files also being installed
(e.g. because your file is a derived class from the other LAMMPS
class), then an Install.sh file is also needed to check for those
dependencies and modifications to src/Depend.sh to trigger the checks.
See other README and Install.sh files in other directories as examples.
Similarly for CMake support changes need to be made to cmake/CMakeLists.txt,
the files in cmake/presets, and possibly a file to cmake/Modules/Packages/
added. Please check out how this is handled for existing packages and
ask the LAMMPS developers if you need assistance. Please submit a pull
request on GitHub or send us a tarball of this FOO directory and all
modified files. Pull requests are strongly encouraged since they greatly
reduce the effort required to integrate a contribution and simplify the
process of adjusting the contributed code to cleanly fit into the
LAMMPS distribution.
* Your new source files need to have the LAMMPS copyright, GPL notice,
and your name and email address at the top, like other
user-contributed LAMMPS source files. They need to create a class
that is inside the LAMMPS namespace. To simplify maintenance, we
may ask to adjust the programming style and formatting style to closer
match the rest of LAMMPS. We bundle a clang-format configuration file
that can help with adjusting the formatting, although this is not a
strict requirement.
* You **must** also create a **documentation** file for each new command
or style you are adding to LAMMPS. For simplicity and convenience,
the documentation of groups of closely related commands or styles may
be combined into a single file. This will be one file for a
single-file feature. For a package, it might be several files. These
are text files with a .rst extension using the `reStructuredText
<rst_>`_ markup language, that are then converted to HTML and PDF
using the `Sphinx <sphinx_>`_ documentation generator tool. Running
Sphinx with the included configuration requires Python 3.x.
Configuration settings and custom extensions for this conversion are
included in the source distribution, and missing python packages will
be transparently downloaded into a virtual environment via pip. Thus,
if your local system is missing required packages, you need access to
the internet. The translation can be as simple as doing "make html
pdf" in the doc folder. As appropriate, the text files can include
inline mathematical expression or figures (see doc/JPG for examples).
Additional PDF files with further details (see doc/PDF for examples)
may also be included. The page should also include literature
citations as appropriate; see the bottom of doc/fix_nh.rst for
examples and the earlier part of the same file for how to format the
cite itself. Citation labels must be unique across all .rst files.
The "Restrictions" section of the page should indicate if your
command is only available if LAMMPS is built with the appropriate
FOO package. See other package doc files for examples of
how to do this. Please run at least "make html" and "make spelling"
and carefully inspect and proofread the resulting HTML format doc page
before submitting your code. Upon submission of a pull request,
checks for error free completion of the HTML and PDF build will be
performed and also a spell check, a check for correct anchors and
labels, and a check for completeness of references all styles in their
corresponding tables and lists is run. In case the spell check
reports false positives they can be added to the file
doc/utils/sphinx-config/false_positives.txt
* For a new package (or even a single command) you should include one or
more example scripts demonstrating its use. These should run in no
more than a couple minutes, even on a single processor, and not require
large data files as input. See directories under examples/PACKAGES for
examples of input scripts other users provided for their packages.
These example inputs are also required for validating memory accesses
and testing for memory leaks with valgrind
* If there is a paper of yours describing your feature (either the
algorithm/science behind the feature itself, or its initial usage, or
its implementation in LAMMPS), you can add the citation to the \*.cpp
source file. See src/EFF/atom_vec_electron.cpp for an example.
A LaTeX citation is stored in a variable at the top of the file and
a single line of code registering this variable is added to the
constructor of the class. If there is additional functionality (which
may have been added later) described in a different publication,
additional citation descriptions may be added for as long as they
are only registered when the corresponding keyword activating this
functionality is used. With these options it is possible to have
LAMMPS output a specific citation reminder whenever a user invokes
your feature from their input script. Note that you should only use
this for the most relevant paper for a feature and a publication that
you or your group authored. E.g. adding a citation in the code for
a paper by Nose and Hoover if you write a fix that implements their
integrator is not the intended usage. That kind of citation should
just be included in the documentation page you provide describing
your contribution. If you are not sure what the best option would
be, please contact the LAMMPS developers for advice.
Finally, as a general rule-of-thumb, the more clear and
self-explanatory you make your documentation and README files, and the
easier you make it for people to get started, e.g. by providing example
scripts, the more likely it is that users will try out your new feature.
.. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html
.. _sphinx: https://sphinx-doc.org

4
doc/src/Modify_overview.rst
View File

@ -40,8 +40,10 @@ then your pair_foo.h file should be structured as follows:
.. code-block:: c++
#ifdef PAIR_CLASS
PairStyle(foo,PairFoo)
// clang-format off
PairStyle(foo,PairFoo);
#else
// clanf-format on
...
(class definition for PairFoo)
...

439
doc/src/Modify_style.rst Normal file
View File

@ -0,0 +1,439 @@
LAMMPS programming style and requirements for contributions
===========================================================
The following is a summary of the current requirements and
recommendations for including contributed source code or documentation
into the LAMMPS software distribution.
Motivation
----------
The LAMMPS developers are committed to providing a software package that
is versatile, reliable, high-quality, efficient, portable, and easy to
maintain and modify. Achieving all of these goals is challenging since
a large part of LAMMPS consists of contributed code from many different
authors and not many of them are professionally trained programmers and
familiar with the idiosyncrasies of maintaining a large software
package. In addition, changes that interfere with the parallel
efficiency of the core code must be avoided. As LAMMPS continues to
grow and more features and functionality are added, it becomes a
necessity to be more discriminating with new contributions while also
working at the same time to improve the existing code.
The following requirements and recommendations are provided to help
maintaining or improving that status. Where possible we utilize
available continuous integration tools to search for common programming
mistakes, portability limitations, incompatible formatting, and
undesired side effects. It is indicated which requirements are strict,
and which represent a preference and thus are negotiable or optional.
Please feel free to contact the LAMMPS core developers in case you need
additional explanations or clarifications or in case you need assistance
in realizing the (strict) requirements for your contributions.
Licensing requirements (strict)
-------------------------------
Contributing authors agree when submitting a pull request that their
contributions can be distributed under the LAMMPS license
conditions. This is the GNU public license in version 2 (not 3 or later)
for the publicly distributed versions, e.g. on the LAMMPS homepage or on
GitHub. On request we also make a version of LAMMPS available under
LGPL 2.1 terms; this will usually be the latest available or a previous
stable version with a few LGPL 2.1 incompatible files removed.
Your new source files should have the LAMMPS copyright, GPL notice, and
your name and email address at the top, like other user-contributed
LAMMPS source files.
Contributions may be under a different license for long as that
license does not conflict with the aforementioned terms. Contributions
that use code with a conflicting license can be split into two parts:
1. the core parts (i.e. parts that must be in the `src` tree) that are
licensed under compatible terms and bundled with the LAMMPS sources
2. an external library that must be downloaded and compiled (either
separately or as part of the LAMMPS compilation)
Please note, that this split licensed mode may complicate including the
contribution in binary packages.
Using Pull Requests on GitHub (preferred)
-----------------------------------------
All contributions to LAMMPS are processed as pull requests on GitHub
(this also applies to the work of the core LAMMPS developers). A
:doc:`tutorial for submitting pull requests on GitHub <Howto_github>` is
provided. If this is still problematic, contributors may contact any of
the core LAMMPS developers for help or to create a pull request on their
behalf. This latter way of submission may delay the integration as it
depends on the amount of time required to prepare the pull request and
free time available by the LAMMPS developer in question to spend on this
task.
Integration Testing (strict)
----------------------------
Contributed code, like all pull requests, must pass the automated
tests on GitHub before it can be merged with the LAMMPS distribution.
These tests compile LAMMPS in a variety of environments and settings and
run the bundled unit tests. At the discretion of the LAMMPS developer
managing the pull request, additional tests may be activated that test
for "side effects" on running a collection of input decks and create
consistent results. Also, the translation of the documentation to HTML
and PDF is tested for.
More specifically, this means that contributed source code **must**
compile with the most current version of LAMMPS with ``-DLAMMPS_BIGBIG``
in addition to the default setting of ``-DLAMMPS_SMALLBIG``. The code
needs to work correctly in both cases and also in serial and parallel
using MPI.
Some "disruptive" changes may break tests and require updates to the
testing tools or scripts or tests themselves. This is rare. If in
doubt, contact the LAMMPS developer that is assigned to the pull request
for further details and explanations and suggestions of what needs to be
done.
Documentation (strict)
----------------------
Contributions that add new styles or commands or augment existing ones
must include the corresponding new or modified documentation in
`ReStructuredText format <rst>`_ (.rst files in the ``doc/src/`` folder). The
documentation shall be written in American English and the .rst file
must use only ASCII characters so it can be cleanly translated to PDF
files (via `sphinx <sphinx>`_ and PDFLaTeX). Special characters may be included via
embedded math expression typeset in a LaTeX subset.
.. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html
When adding new commands, they need to be integrated into the sphinx
documentation system, and the corresponding command tables and lists
updated. When translating the documentation into html files there should
be no warnings. When adding a new package also some lists describing
packages must be updated as well as a package specific description added
and, if necessary, some package specific build instructions included.
As appropriate, the text files with the documentation can include inline
mathematical expression or figures (see ``doc/JPG`` for examples).
Additional PDF files with further details (see ``doc/PDF`` for examples) may
also be included. The page should also include literature citations as
appropriate; see the bottom of ``doc/fix_nh.rst`` for examples and the
earlier part of the same file for how to format the cite itself.
Citation labels must be unique across **all** .rst files. The
"Restrictions" section of the page should indicate if your command is
only available if LAMMPS is built with the appropriate FOO package. See
other package doc files for examples of how to do this.
Please run at least "make html" and "make spelling" and carefully
inspect and proofread the resulting HTML format doc page before
submitting your code. Upon submission of a pull request, checks for
error free completion of the HTML and PDF build will be performed and
also a spell check, a check for correct anchors and labels, and a check
for completeness of references all styles in their corresponding tables
and lists is run. In case the spell check reports false positives they
can be added to the file doc/utils/sphinx-config/false_positives.txt
Contributions that add or modify the library interface or "public" APIs
from the C++ code or the Fortran module must include suitable doxygen
comments in the source and corresponding changes to the documentation
sources for the "Programmer Guide" guide section of the LAMMPS manual.
Examples (preferred)
--------------------
In most cases, it is preferred that example scripts (simple, small, fast
to complete on 1 CPU) are included that demonstrate the use of new or
extended functionality. These are typically under the examples or
examples/PACKAGES directory. A few guidelines for such example input
decks.
- commands that generate output should be commented out (except when the
output is the sole purpose or the feature, e.g. for a new compute).
- commands like :doc:`log <log>`, :doc:`echo <echo>`, :doc:`package
<package>`, :doc:`processors <processors>`, :doc:`suffix <suffix>` may
**not** be used in the input file (exception: "processors * * 1" or
similar is acceptable when used to avoid unwanted domain decomposition
of empty volumes).
- outside of the log files no generated output should be included
- custom thermo_style settings may not include output measuring CPU or other time
as that makes comparing the thermo output between different runs more complicated.
- input files should be named ``in.name``, data files should be named
``data.name`` and log files should be named ``log.version.name.<compiler>.<ncpu>``
- the total file size of all the inputs and outputs should be small
- where possible potential files from the "potentials" folder or data
file from other folders should be re-used through symbolic links
Howto document (optional)
-------------------------
If your feature requires some more complex steps and explanations to be
used correctly or some external or bundled tools or scripts, we
recommend that you also contribute a :doc:`Howto document <Howto>`
providing some more background information and some tutorial material.
This can also be used to provide more in-depth explanations for bundled
examples.
As a general rule-of-thumb, the more clear and self-explanatory you make
your documentation, README files and examples, and the easier you make
it for people to get started, the more likely it is that users will try
out your new feature.
Programming Style Requirements (varied)
---------------------------------------
The LAMMPS developers aim to employ a consistent programming style and
naming conventions across the entire code base, as this helps with
maintenance, debugging, and understanding the code, both for developers
and users.
The files `pair_lj_cut.h`, `pair_lj_cut.cpp`, `utils.h`, and `utils.cpp`
may serve as representative examples.
Command or Style names, file names, and keywords (mostly strict)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All user-visible command or style names should be all lower case and
should only use letters, numbers, or forward slashes. They should be
descriptive and initialisms should be avoided unless they are well
established (e.g. lj for Lennard-Jones). For a compute style
"some/name" the source files must be called `compute_some_name.h` and
`compute_some_name.cpp`. The "include guard" would then be
`LMP_COMPUTE_SOME_NAME_H` and the class name `ComputeSomeName`.
Whitespace and permissions (preferred)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Source files should not contain TAB characters unless required by the
syntax (e.g. in makefiles) and no trailing whitespace. Text files
should be added with Unix-style line endings (LF-only). Git will
automatically convert those in both directions when running on Windows;
use dos2unix on Linux machines to convert files. Text files should have
a line ending on the last line.
All files should have 0644 permissions, i.e writable to the user only
and readable by all and no executable permissions. Executable
permissions (0755) should only be on shell scripts or python or similar
scripts for interpreted script languages.
Indentation and Placement of Braces (strongly preferred)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
LAMMPS uses 2 characters per indentation level and lines should be
kept within 100 characters wide.
For new files added to the "src" tree, a `clang-format
<https://clang.llvm.org/docs/ClangFormat.html>`_ configuration file is
provided under the name `.clang-format`. This file is compatible with
clang-format version 8 and later. With that file present files can be
reformatted according to the configuration with a command like:
`clang-format -i new-file.cpp`. Ideally, this is done while writing the
code or before a pull request is submitted. Blocks of code where the
reformatting from clang-format yields undesirable output may be
protected with placing a pair `// clang-format off` and `// clang-format
on` comments around that block.
Programming language standards (required)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The core of LAMMPS is written in C++11 in a style that can be mostly
described as "C with classes". Advanced C++ features like operator
overloading or excessive use of templates are avoided with the intent to
keep the code readable to programmers that have limited C++ programming
experience. C++ constructs are acceptable when they help improving the
readability and reliability of the code, e.g. when using the
`std::string` class instead of manipulating pointers and calling the
string functions of the C library. In addition and number of convenient
:doc:`utility functions and classes <Developer_utils>` for recurring
tasks are provided.
Included Fortran code has to be compatible with the Fortran 2003
standard. Python code must be compatible with Python 3.5. Large parts
or LAMMPS (including the :ref:`PYTHON package <PKG-PYTHON>`) are also
compatible with Python 2.7. Compatibility with Python 2.7 is
desirable, but compatibility with Python 3.5 is **required**.
Compatibility with these older programming language standards is very
important to maintain portability, especially with HPC cluster
environments, which tend to be running older software stacks and LAMMPS
users may be required to use those older tools or not have the option to
install newer compilers.
Programming conventions (varied)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following is a collection of conventions that should be applied when
writing code for LAMMPS. Following these steps will make it much easier
to integrate your contribution. Please have a look at the existing files
in packages in the src directory for examples. As a demonstration for
how can be adapted to these conventions you may compare the REAXFF
package with the what it looked like when it was called USER-REAXC. If
you are uncertain, please ask.
- system headers or from installed libraries are include with angular
brackets (example: ``#include <vector>``), while local include file
use double quotes (example: ``#include "atom.h"``).
- when including system header files from the C library use the
C++-style names (``<cstdlib>`` or ``<cstring>``) instead of the
C-style names (``<stdlib.h>`` or ``<string.h>``)
- the order of ``#include`` statements in a file ``some_name.cpp`` that
implements a class ``SomeName`` defined in a header file
``some_name.h`` should be as follows:
- ``#include "some_name.h"`` followed by an empty line
- LAMMPS include files e.g. ``#include "comm.h"`` or ``#include
"modify.h"`` in alphabetical order followed by an empty line
- system header files from the C++ or C standard library followed by
an empty line
- ``using namespace LAMMPS_NS`` or other namespace imports.
- I/O is done via the C-style stdio library and **not** iostreams.
- 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.
- Header files, especially those defining a "style", should only use
the absolute minimum number of include files and **must not** contain
any ``using`` statements. Typically that would be only the header for
the base class. Instead any include statements should be put into the
corresponding implementation files and forward declarations be used.
For implementation files, the "include what you use" principle should
be employed. However, there is the notable exception that when the
``pointers.h`` header is included (or one of the base classes derived
from it) certain headers will always be included and thus do not need
to be explicitly specified.
These are: `mpi.h`, `cstddef`, `cstdio`, `cstdlib`, `string`, `utils.h`,
`vector`, `fmt/format.h`, `climits`, `cinttypes`.
This also means any such file can assume that `FILE`, `NULL`, and
`INT_MAX` are defined.
- Header files that define a new LAMMPS style (i.e. that have a
``SomeStyle(some/name,SomeName);`` macro in them) should only use the
include file for the base class and otherwise use forward declarations
and pointers; when interfacing to a library use the PIMPL (pointer
to implementation) approach where you have a pointer to a struct
that contains all library specific data (and thus requires the library
header) but use a forward declaration and define the struct only in
the implementation file. This is a **strict** requirement since this
is where type clashes between packages and hard to find bugs have
regularly manifested in the past.
- Please use clang-format only to reformat files that you have
contributed. For header files containing a ``SomeStyle(keyword,
ClassName)`` macros it is required to have this macro embedded with a
pair of ``// clang-format off``, ``// clang-format on`` commends and
the line must be terminated with a semi-colon (;). Example:
.. code-block:: c++
#ifdef COMMAND_CLASS
// clang-format off
CommandStyle(run,Run);
// clang-format on
#else
#ifndef LMP_RUN_H
[...]
You may also use ``// clang-format on/off`` throughout your files
to protect individual sections from being reformatted.
- We rarely accept new styles in the core src folder. Thus please
review the list of :doc:`available Packages <Packages_details>` to see
if your contribution could be added to be added to one of them. It
should fit into the general purposed of that package. If it does not
fit well, it may be added to one of the EXTRA- packages or the MISC
package.
Contributing a package
----------------------
If your contribution has several related features that are not covered
by one of the existing packages or is dependent on a library (bundled or
external), it is best to make it a package directory with a name like
FOO. In addition to your new files, the directory should contain a
README text file. The README should contain your name and contact
information and a brief description of what your new package does.
Build system (strongly preferred)
---------------------------------
LAMMPS currently supports two build systems: one that is based on
:doc:`traditional Makefiles <Build_make>` and one that is based on
:doc:`CMake <Build_cmake>`. Thus your contribution must be compatible
with and support both.
For a single pair of header and implementation files that are an
independent feature, it is usually only required to add them to
`src/.gitignore``.
For traditional make, if your contributed files or package depend on
other LAMMPS style files or packages also being installed (e.g. because
your file is a derived class from the other LAMMPS class), then an
Install.sh file is also needed to check for those dependencies and
modifications to src/Depend.sh to trigger the checks. See other README
and Install.sh files in other directories as examples.
Similarly for CMake support, changes may need to be made to
cmake/CMakeLists.txt, some of the files in cmake/presets, and possibly a
file with specific instructions needs to be added to
cmake/Modules/Packages/. Please check out how this is handled for
existing packages and ask the LAMMPS developers if you need assistance.
Citation reminder (suggested)
-----------------------------
If there is a paper of yours describing your feature (either the
algorithm/science behind the feature itself, or its initial usage, or
its implementation in LAMMPS), you can add the citation to the \*.cpp
source file. See ``src/DIFFRACTION/compute_saed.cpp`` for an example.
A BibTeX format citation is stored in a string variable at the top
of the file and a single line of code registering this variable is
added to the constructor of the class. When your feature is used,
by default, LAMMPS will print the brief info and the DOI
in the first line to the screen and the full citation to the log file.
If there is additional functionality (which may have been added later)
described in a different publication, additional citation descriptions
may be added for as long as they are only registered when the
corresponding keyword activating this functionality is used. With these
options it is possible to have LAMMPS output a specific citation
reminder whenever a user invokes your feature from their input script.
Please note that you should *only* use this for the *most* relevant
paper for a feature and a publication that you or your group authored.
E.g. adding a citation in the code for a paper by Nose and Hoover if you
write a fix that implements their integrator is not the intended usage.
That latter kind of citation should just be included in the
documentation page you provide describing your contribution. If you are
not sure what the best option would be, please contact the LAMMPS
developers for advice.
Testing (optional)
------------------
If your contribution contains new utility functions or a supporting class
(i.e. anything that does not depend on a LAMMPS object), new unit tests
should be added to a suitable folder in the ``unittest`` tree.
When adding a new LAMMPS style computing forces or selected fixes,
a ``.yaml`` file with a test configuration and reference data should be
added for the styles where a suitable tester program already exists
(e.g. pair styles, bond styles, etc.). Please see
:ref:`this section in the manual <testing>` for more information on
how to enable, run, and expand testing.

BIN
doc/src/PDF/CG-DNA.pdf
View File

Binary file not shown.

BIN
doc/src/PDF/colvars-refman-lammps.pdf
View File

Binary file not shown.

26
doc/src/Packages_details.rst
View File

@ -944,7 +944,7 @@ This package has :ref:`specific installation instructions <gpu>` on the :doc:`Bu
* :doc:`package gpu <package>`
* :doc:`Commands <Commands_all>` pages (:doc:`pair <Commands_pair>`, :doc:`kspace <Commands_kspace>`)
for styles followed by (g)
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of web site
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of website
----------
@ -1056,7 +1056,7 @@ This package has :ref:`specific installation instructions <intel>` on the :doc:`
* Search the :doc:`commands <Commands_all>` pages (:doc:`fix <Commands_fix>`, :doc:`compute <Commands_compute>`,
:doc:`pair <Commands_pair>`, :doc:`bond, angle, dihedral, improper <Commands_bond>`, :doc:`kspace <Commands_kspace>`) for styles followed by (i)
* src/INTEL/TEST
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of web site
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of website
----------
@ -1193,7 +1193,7 @@ This package has :ref:`specific installation instructions <kokkos>` on the :doc:
* Search the :doc:`commands <Commands_all>` pages (:doc:`fix <Commands_fix>`, :doc:`compute <Commands_compute>`,
:doc:`pair <Commands_pair>`, :doc:`bond, angle, dihedral, improper <Commands_bond>`,
:doc:`kspace <Commands_kspace>`) for styles followed by (k)
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of web site
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of website
----------
@ -1271,7 +1271,7 @@ A fix command which wraps the LATTE DFTB code, so that molecular
dynamics can be run with LAMMPS using density-functional tight-binding
quantum forces calculated by LATTE.
More information on LATTE can be found at this web site:
More information on LATTE can be found at this website:
`https://github.com/lanl/LATTE <latte-home_>`_. A brief technical
description is given with the :doc:`fix latte <fix_latte>` command.
@ -2045,7 +2045,7 @@ the :doc:`Build extras <Build_extras>` page.
* Search the :doc:`commands <Commands_all>` pages (:doc:`fix <Commands_fix>`, :doc:`compute <Commands_compute>`,
:doc:`pair <Commands_pair>`, :doc:`bond, angle, dihedral, improper <Commands_bond>`,
:doc:`kspace <Commands_kspace>`) for styles followed by (o)
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of web site
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of website
----------
@ -2079,7 +2079,7 @@ This package has :ref:`specific installation instructions <opt>` on the :doc:`Bu
* :doc:`OPT package <Speed_opt>`
* :doc:`Section 2.6 -sf opt <Run_options>`
* Search the :doc:`pair style <Commands_pair>` page for styles followed by (t)
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of web site
* `Benchmarks page <https://www.lammps.org/bench.html>`_ of website
.. _PKG-ORIENT:
@ -2276,16 +2276,16 @@ PYTHON package
A :doc:`python <python>` command which allow you to execute Python code
from a LAMMPS input script. The code can be in a separate file or
embedded in the input script itself. See the :doc:`Python call <Python_call>` page for an overview of using Python from
LAMMPS in this manner and all the :doc:`Python <Python_head>` manual pages
for other ways to use LAMMPS and Python together.
embedded in the input script itself. See the :doc:`Python call
<Python_call>` page for an overview of using Python from LAMMPS in this
manner and all the :doc:`Python <Python_head>` manual pages for other
ways to use LAMMPS and Python together.
.. note::
Building with the PYTHON package assumes you have a Python
shared library available on your system, which needs to be a Python 2
version, 2.6 or later. Python 3 is not yet supported. See the
lib/python/README for more details.
Building with the PYTHON package assumes you have a Python development
environment (headers and libraries) available on your system, which needs
to be either Python version 2.7 or Python 3.5 and later.
**Install:**

16
doc/src/Run_basics.rst
View File

@ -2,17 +2,25 @@ Basics of running LAMMPS
========================
LAMMPS is run from the command line, reading commands from a file via
the -in command line flag, or from standard input.
Using the "-in in.file" variant is recommended:
the -in command line flag, or from standard input. Using the "-in
in.file" variant is recommended (see note below). The name of the
LAMMPS executable is either ``lmp`` or ``lmp_<machine>`` with
`<machine>` being the machine string used when compiling LAMMPS. This
is required when compiling LAMMPS with the traditional build system
(e.g. with ``make mpi``), but optional when using CMake to configure and
build LAMMPS:
.. code-block:: bash
$ lmp_serial -in in.file
$ lmp_serial < in.file
$ lmp -in in.file
$ lmp < in.file
$ /path/to/lammps/src/lmp_serial -i in.file
$ mpirun -np 4 lmp_mpi -in in.file
$ mpiexec -np 4 lmp -in in.file
$ mpirun -np 8 /path/to/lammps/src/lmp_mpi -in in.file
$ mpirun -np 6 /usr/local/bin/lmp -in in.file
$ mpiexec -n 6 /usr/local/bin/lmp -in in.file
You normally run the LAMMPS command in the directory where your input
script is located. That is also where output files are produced by
@ -23,7 +31,7 @@ executable itself can be placed elsewhere.
.. note::
The redirection operator "<" will not always work when running
in parallel with mpirun; for those systems the -in form is required.
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

27
doc/src/Run_options.rst
View File

@ -2,7 +2,7 @@ Command-line options
====================
At run time, LAMMPS recognizes several optional command-line switches
which may be used in any order. Either the full word or a one-or-two
which may be used in any order. Either the full word or a one or two
letter abbreviation can be used:
* :ref:`-e or -echo <echo>`
@ -22,6 +22,7 @@ letter abbreviation can be used:
* :ref:`-r2data or -restart2data <restart2data>`
* :ref:`-r2dump or -restart2dump <restart2dump>`
* :ref:`-sc or -screen <screen>`
* :ref:`-sr or skiprun <skiprun>`
* :ref:`-sf or -suffix <suffix>`
* :ref:`-v or -var <var>`
@ -241,10 +242,11 @@ links with from the lib/message directory. See the
**-cite style** or **file name**
Select how and where to output a reminder about citing contributions
to the LAMMPS code that were used during the run. Available styles are
"both", "none", "screen", or "log". Any flag will be considered a file
name to write the detailed citation info to. Default is the "log" style
where there is a short summary in the screen output and detailed citations
to the LAMMPS code that were used during the run. Available keywords
for styles are "both", "none", "screen", or "log". Any other keyword
will be considered a file name to write the detailed citation info to
instead of logfile or screen. Default is the "log" style where there
is a short summary in the screen output and detailed citations
in BibTeX format in the logfile. The option "both" selects the detailed
output for both, "none", the short output for both, and "screen" will
write the detailed info to the screen and the short version to the log
@ -532,6 +534,21 @@ partition screen files file.N.
----------
.. _skiprun:
**-skiprun**
Insert the command :doc:`timer timeout 0 every 1 <timer>` at the
beginning of an input file or after a :doc:`clear <clear>` command.
This has the effect that the entire LAMMPS input script is processed
without executing actual :doc:`run <run>` or :doc:`minimize <minimize>`
and similar commands (their main loops are skipped). This can be
helpful and convenient to test input scripts of long running
calculations for correctness to avoid having them crash after a
long time due to a typo or syntax error in the middle or at the end.
----------
.. _suffix:
**-suffix style args**

4
doc/src/Speed.rst
View File

@ -13,8 +13,8 @@ for certain kinds of hardware, including multi-core CPUs, GPUs, and
Intel Xeon Phi co-processors.
The `Benchmark page <https://www.lammps.org/bench.html>`_ of the LAMMPS
web site gives performance results for the various accelerator
packages discussed on the :doc:`Speed packages <Speed_packages>` doc
website gives performance results for the various accelerator
packages discussed on the :doc:`Accelerator packages <Speed_packages>`
page, for several of the standard LAMMPS benchmark problems, as a
function of problem size and number of compute nodes, on different
hardware platforms.

2
doc/src/Speed_gpu.rst
View File

@ -153,7 +153,7 @@ usually resulting in inferior performance compared to using LAMMPS' native
threading and vectorization support in the OPENMP and INTEL packages.
See the `Benchmark page <https://www.lammps.org/bench.html>`_ of the
LAMMPS web site for performance of the GPU package on various
LAMMPS website for performance of the GPU package on various
hardware, including the Titan HPC platform at ORNL.
You should also experiment with how many MPI tasks per GPU to use to

2
doc/src/Speed_kokkos.rst
View File

@ -407,7 +407,7 @@ Generally speaking, the following rules of thumb apply:
by switching to single or mixed precision mode.
See the `Benchmark page <https://www.lammps.org/bench.html>`_ of the
LAMMPS web site for performance of the KOKKOS package on different
LAMMPS website for performance of the KOKKOS package on different
hardware.
Advanced Kokkos options

2
doc/src/Speed_packages.rst
View File

@ -144,7 +144,7 @@ sub-directories with Make.py commands and input scripts for using all
the accelerator packages on various machines. See the README files in
those directories.
As mentioned above, the `Benchmark page <https://www.lammps.org/bench.html>`_ of the LAMMPS web site gives
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
size and number of compute nodes, on different hardware platforms.

4
doc/src/Tools.rst
View File

@ -7,7 +7,7 @@ steps are often necessary to setup and analyze a simulation. A list
of such tools can be found on the `LAMMPS webpage <lws_>`_ at these links:
* `Pre/Post processing <https://www.lammps.org/prepost.html>`_
* `Offsite LAMMPS packages & tools <https://www.lammps.org/offsite.html>`_
* `External LAMMPS packages & tools <https://www.lammps.org/external.html>`_
* `Pizza.py toolkit <pizza_>`_
The last link for `Pizza.py <pizza_>`_ is a Python-based tool developed at
@ -172,7 +172,7 @@ Chris Lorenz (chris.lorenz at kcl.ac.uk), King's College London.
chain tool
----------------------
The file chain.f creates a LAMMPS data file containing bead-spring
The file chain.f90 creates a LAMMPS data file containing bead-spring
polymer chains and/or monomer solvent atoms. It uses a text file
containing chain definition parameters as an input. The created
chains and solvent atoms can strongly overlap, so LAMMPS needs to run

4
doc/src/accel_styles.rst
View File

@ -1,7 +1,7 @@
Styles with a *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed on the :doc:`Speed packages <Speed_packages>` doc
hardware, as discussed on the :doc:`Accelerator packages <Speed_packages>`
page. The accelerated styles take the same arguments and should
produce the same results, except for round-off and precision issues.
@ -13,5 +13,5 @@ You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :doc:`-suffix command-line switch <Run_options>` when you invoke LAMMPS, or you can use the
:doc:`suffix <suffix>` command in your input script.
See the :doc:`Speed packages <Speed_packages>` page for more
See the :doc:`Accelerator packages <Speed_packages>` page for more
instructions on how to use the accelerated styles effectively.

18
doc/src/angle_charmm.rst
View File

@ -56,23 +56,7 @@ radian\^2.
----------
Styles with a *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed on the :doc:`Speed packages <Speed_packages>` doc
page. The accelerated styles take the same arguments and should
produce the same results, except for round-off and precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS,
OPENMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the :doc:`Build package <Build_package>` page for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :doc:`-suffix command-line switch <Run_options>` when you invoke LAMMPS, or you can use the
:doc:`suffix <suffix>` command in your input script.
See :doc:`Speed packages <Speed_packages>` page for more
instructions on how to use the accelerated styles effectively.
.. include:: accel_styles.rst
----------

23
doc/src/atom_style.rst
View File

@ -325,28 +325,9 @@ styles; see the :doc:`Modify <Modify>` doc page.
----------
Styles with a *kk* suffix are functionally the same as the
corresponding style without the suffix. They have been optimized to
run faster, depending on your available hardware, as discussed in on
the :doc:`Speed packages <Speed_packages>` doc page. The accelerated
styles take the same arguments and should produce the same results,
except for round-off and precision issues.
.. include:: accel_styles.rst
Note that other acceleration packages in LAMMPS, specifically the GPU,
INTEL, OPENMP, and OPT packages do not use accelerated atom
styles.
The accelerated styles are part of the KOKKOS package. They are only
enabled if LAMMPS was built with those packages. See the :doc:`Build
package <Build_package>` page for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :doc:`-suffix command-line
switch <Run_options>` when you invoke LAMMPS, or you can use the
:doc:`suffix <suffix>` command in your input script.
See the :doc:`Speed packages <Speed_packages>` page for more
instructions on how to use the accelerated styles effectively.
----------
Restrictions
""""""""""""

6
doc/src/bond_oxdna.rst
View File

@ -99,10 +99,10 @@ duplexes or arrays of DNA/RNA duplexes can be found in
examples/PACKAGES/cgdna/util/.
Please cite :ref:`(Henrich) <Henrich0>` in any publication that uses
this implementation. The article contains general information
this implementation. An updated documentation that contains general information
on the model, its implementation and performance as well as the structure of
the data and input file. The preprint version of the article can be found
`here <PDF/CG-DNA.pdf>`_.
the data and input file can be found `here <PDF/CG-DNA.pdf>`_.
Please cite also the relevant oxDNA/oxRNA publications. These are
:ref:`(Ouldridge) <Ouldridge0>` and
:ref:`(Ouldridge-DPhil) <Ouldridge-DPhil0>` for oxDNA,

26
doc/src/compute_angle.rst
View File

@ -23,22 +23,23 @@ Examples
Description
"""""""""""
Define a computation that extracts the angle energy calculated by each
of the angle sub-styles used in the doc:`angle_style hybrid <angle_hybrid>`
command. These values are made accessible
for output or further processing by other commands. The group
specified for this command is ignored.
Define a computation that extracts the angle energy calculated by each of the
angle sub-styles used in the :doc:`angle_style hybrid <angle_hybrid>` command.
These values are made accessible for output or further processing by other
commands. The group specified for this command is ignored.
This compute is useful when using :doc:`angle_style hybrid <angle_hybrid>` if you want to know the portion of the total
energy contributed by one or more of the hybrid sub-styles.
This compute is useful when using :doc:`angle_style hybrid <angle_hybrid>` if
you want to know the portion of the total energy contributed by one or more of
the hybrid sub-styles.
Output info
"""""""""""
This compute calculates a global vector of length N where N is the
number of sub_styles defined by the :doc:`angle_style hybrid <angle_style>` command, which can be accessed by indices
1-N. These values can be used by any command that uses global scalar
or vector values from a compute as input. See the :doc:`Howto output <Howto_output>` page for an overview of LAMMPS output
This compute calculates a global vector of length N where N is the number of
sub_styles defined by the :doc:`angle_style hybrid <angle_style>` command,
which can be accessed by indices 1-N. These values can be used by any command
that uses global scalar or vector values from a compute as input. See the
:doc:`Howto output <Howto_output>` page for an overview of LAMMPS output
options.
The vector values are "extensive" and will be in energy
@ -46,7 +47,8 @@ The vector values are "extensive" and will be in energy
Restrictions
""""""""""""
none
none
Related commands
""""""""""""""""

5
doc/src/fix.rst
View File

@ -166,6 +166,7 @@ page are followed by one or more of (g,i,k,o,t) to indicate which
accelerated styles exist.
* :doc:`accelerate/cos <fix_accelerate_cos>` - apply cosine-shaped acceleration to atoms
* :doc:`acks2/reaxff <fix_acks2_reaxff>` - apply ACKS2 charge equilibration
* :doc:`adapt <fix_adapt>` - change a simulation parameter over time
* :doc:`adapt/fep <fix_adapt_fep>` - enhanced version of fix adapt
* :doc:`addforce <fix_addforce>` - add a force to each atom
@ -246,6 +247,7 @@ accelerated styles exist.
* :doc:`manifoldforce <fix_manifoldforce>` - restrain atoms to a manifold during minimization
* :doc:`mdi/engine <fix_mdi_engine>` - connect LAMMPS to external programs via the MolSSI Driver Interface (MDI)
* :doc:`meso/move <fix_meso_move>` - move mesoscopic SPH/SDPD particles in a prescribed fashion
* :doc:`mol/swap <fix_mol_swap>` - Monte Carlo atom type swapping with a molecule
* :doc:`momentum <fix_momentum>` - zero the linear and/or angular momentum of a group of atoms
* :doc:`momentum/chunk <fix_momentum>` - zero the linear and/or angular momentum of a chunk of atoms
* :doc:`move <fix_move>` - move atoms in a prescribed fashion
@ -379,7 +381,8 @@ accelerated styles exist.
* :doc:`thermal/conductivity <fix_thermal_conductivity>` - Muller-Plathe kinetic energy exchange for thermal conductivity calculation
* :doc:`ti/spring <fix_ti_spring>` -
* :doc:`tmd <fix_tmd>` - guide a group of atoms to a new configuration
* :doc:`ttm <fix_ttm>` - two-temperature model for electronic/atomic coupling
* :doc:`ttm <fix_ttm>` - two-temperature model for electronic/atomic coupling (replicated grid)
* :doc:`ttm/grid <fix_ttm>` - two-temperature model for electronic/atomic coupling (distributed grid)
* :doc:`ttm/mod <fix_ttm>` - enhanced two-temperature model with additional options
* :doc:`tune/kspace <fix_tune_kspace>` - auto-tune KSpace parameters
* :doc:`update/special/bonds <fix_update_special_bonds>` - update special bond lists for BPM bond styles that allow for bond breakage

118
doc/src/fix_acks2_reaxff.rst Normal file
View File

@ -0,0 +1,118 @@
.. index:: fix acks2/reaxff
.. index:: fix acks2/reaxff/kk
fix acks2/reaxff command
========================
Accelerator Variants: *acks2/reaxff/kk*
Syntax
""""""
.. parsed-literal::
fix ID group-ID acks2/reaxff Nevery cutlo cuthi tolerance params args
* ID, group-ID are documented in :doc:`fix <fix>` command
* acks2/reaxff = style name of this fix command
* Nevery = perform ACKS2 every this many steps
* cutlo,cuthi = lo and hi cutoff for Taper radius
* tolerance = precision to which charges will be equilibrated
* params = reaxff or a filename
Examples
""""""""
.. code-block:: LAMMPS
fix 1 all acks2/reaxff 1 0.0 10.0 1.0e-6 reaxff
fix 1 all acks2/reaxff 1 0.0 10.0 1.0e-6 param.acks2
Description
"""""""""""
Perform the atom-condensed Kohn-Sham DFT to second order (ACKS2) charge
equilibration method as described in :ref:`(Verstraelen) <Verstraelen>`.
ACKS2 impedes unphysical long-range charge transfer sometimes seen with
QEq (e.g. for dissociation of molecules), at increased computational
cost. It is typically used in conjunction with the ReaxFF force field
model as implemented in the :doc:`pair_style reaxff <pair_reaxff>`
command, but it can be used with any potential in LAMMPS, so long as it
defines and uses charges on each atom. For more technical details about
the charge equilibration performed by fix acks2/reaxff, see the
:ref:`(O'Hearn) <O'Hearn>` paper.
The ACKS2 method minimizes the electrostatic energy of the system by
adjusting the partial charge on individual atoms based on interactions
with their neighbors. It requires some parameters for each atom type.
If the *params* setting above is the word "reaxff", then these are
extracted from the :doc:`pair_style reaxff <pair_reaxff>` command and
the ReaxFF force field file it reads in. If a file name is specified
for *params*\ , then the parameters are taken from the specified file
and the file must contain one line for each atom type. The latter form
must be used when performing QeQ with a non-ReaxFF potential. The lines
should be formatted as follows:
.. parsed-literal::
bond_softness
itype chi eta gamma bcut
where the first line is the global parameter *bond_softness*. The
remaining 1 to Ntypes lines include *itype*, the atom type from 1 to
Ntypes, *chi*, the electronegativity in eV, *eta*, the self-Coulomb
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 A, eV, and electronic charge.
**Restart, fix_modify, output, run start/stop, minimize info:**
No information about this fix is written to :doc:`binary restart files
<restart>`. No global scalar or vector 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 invoked during :doc:`energy minimization <minimize>`.
----------
.. include:: accel_styles.rst
----------
Restrictions
""""""""""""
This fix is part of the REAXFF package. It is only enabled if LAMMPS
was built with that package. See the :doc:`Build package
<Build_package>` doc page for more info.
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 10 angstroms.
This fix may be used in combination with :doc:`fix efield <fix_efield>`
and will apply the external electric field during charge equilibration,
but there may be only one fix efield instance used, it may only use a
constant electric field, and the electric field vector may only have
components in non-periodic directions.
Related commands
""""""""""""""""
:doc:`pair_style reaxff <pair_reaxff>`, :doc:`fix qeq/reaxff <fix_qeq_reaxff>`
**Default:** none
----------
.. _O'Hearn:
**(O'Hearn)** O'Hearn, Alperen, Aktulga, SIAM J. Sci. Comput., 42(1), C1-C22 (2020).
.. _Verstraelen:
**(Verstraelen)** Verstraelen, Ayers, Speybroeck, Waroquier, J. Chem. Phys. 138, 074108 (2013).

103
doc/src/fix_atom_swap.rst
View File

@ -73,51 +73,51 @@ is the same after the swap as it was before the swap, even though the
atom masses have changed.
The *semi-grand* keyword can be set to *yes* to switch to the
semi-grand canonical ensemble as discussed in :ref:`(Sadigh) <Sadigh>`. This
means that the total number of each particle type does not need to be
conserved. The default is *no*, which means that the only kind of swap
allowed exchanges an atom of one type with an atom of a different
given type. In other words, the relative mole fractions of the swapped
atoms remains constant. Whereas in the semi-grand canonical ensemble,
the composition of the system can change. Note that when using
*semi-grand*, atoms in the fix group whose type is not listed
in the *types* keyword are ineligible for attempted
conversion. An attempt is made to switch
the selected atom (if eligible) to one of the other listed types
with equal probability. Acceptance of each attempt depends upon the Metropolis criterion.
semi-grand canonical ensemble as discussed in :ref:`(Sadigh)
<Sadigh>`. This means that the total number of each particle type does
not need to be conserved. The default is *no*, which means that the
only kind of swap allowed exchanges an atom of one type with an atom
of a different given type. In other words, the relative mole fractions
of the swapped atoms remains constant. Whereas in the semi-grand
canonical ensemble, the composition of the system can change. Note
that when using *semi-grand*, atoms in the fix group whose type is not
listed in the *types* keyword are ineligible for attempted
conversion. An attempt is made to switch the selected atom (if
eligible) to one of the other listed types with equal
probability. Acceptance of each attempt depends upon the Metropolis
criterion.
The *mu* keyword allows users to specify chemical
potentials. This is required and allowed only when using *semi-grand*\ .
All chemical potentials are absolute, so there is one for
each swap type listed following the *types* keyword.
In semi-grand canonical ensemble simulations the chemical composition
of the system is controlled by the difference in these values. So
shifting all values by a constant amount will have no effect
on the simulation.
The *mu* keyword allows users to specify chemical potentials. This is
required and allowed only when using *semi-grand*\ . All chemical
potentials are absolute, so there is one for each swap type listed
following the *types* keyword. In semi-grand canonical ensemble
simulations the chemical composition of the system is controlled by
the difference in these values. So shifting all values by a constant
amount will have no effect on the simulation.
This command may optionally use the *region* keyword to define swap
volume. The specified region must have been previously defined with a
:doc:`region <region>` command. It must be defined with side = *in*\ .
Swap attempts occur only between atoms that are both within the
:doc:`region <region>` command. It must be defined with side = *in*\
. Swap attempts occur only between atoms that are both within the
specified region. Swaps are not otherwise attempted.
You should ensure you do not swap atoms belonging to a molecule, or
LAMMPS will soon generate an error when it tries to find those atoms.
LAMMPS will warn you if any of the atoms eligible for swapping have a
non-zero molecule ID, but does not check for this at the time of
LAMMPS will eventually generate an error when it tries to find those
atoms. LAMMPS will warn you if any of the atoms eligible for swapping
have a non-zero molecule ID, but does not check for this at the time of
swapping.
If not using *semi-grand* this fix checks to ensure all atoms of the
given types have the same atomic charge. LAMMPS does not enforce this
in general, but it is needed for this fix to simplify the
swapping procedure. Successful swaps will swap the atom type and charge
of the swapped atoms. Conversely, when using *semi-grand*, it is assumed that all the atom
types involved in switches have the same charge. Otherwise, charge
would not be conserved. As a consequence, no checks on atomic charges are
performed, and successful switches update the atom type but not the
atom charge. While it is possible to use *semi-grand* with groups of
atoms that have different charges, these charges will not be changed when the
atom types change.
in general, but it is needed for this fix to simplify the swapping
procedure. Successful swaps will swap the atom type and charge of the
swapped atoms. Conversely, when using *semi-grand*, it is assumed that
all the atom types involved in switches have the same
charge. Otherwise, charge would not be conserved. As a consequence, no
checks on atomic charges are performed, and successful switches update
the atom type but not the atom charge. While it is possible to use
*semi-grand* with groups of atoms that have different charges, these
charges will not be changed when the atom types change.
Since this fix computes total potential energies before and after
proposed swaps, so even complicated potential energy calculations are
@ -133,23 +133,24 @@ OK, including the following:
Some fixes have an associated potential energy. Examples of such fixes
include: :doc:`efield <fix_efield>`, :doc:`gravity <fix_gravity>`,
:doc:`addforce <fix_addforce>`, :doc:`langevin <fix_langevin>`,
:doc:`restrain <fix_restrain>`, :doc:`temp/berendsen <fix_temp_berendsen>`,
:doc:`temp/rescale <fix_temp_rescale>`, and :doc:`wall fixes <fix_wall>`.
For that energy to be included in the total potential energy of the
system (the quantity used when performing GCMC moves),
you MUST enable the :doc:`fix_modify <fix_modify>` *energy* option for
that fix. The doc pages for individual :doc:`fix <fix>` commands
specify if this should be done.
:doc:`restrain <fix_restrain>`, :doc:`temp/berendsen
<fix_temp_berendsen>`, :doc:`temp/rescale <fix_temp_rescale>`, and
:doc:`wall fixes <fix_wall>`. For that energy to be included in the
total potential energy of the system (the quantity used when
performing GCMC moves), you MUST enable the :doc:`fix_modify
<fix_modify>` *energy* option for that fix. The doc pages for
individual :doc:`fix <fix>` commands specify if this should be done.
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
This fix writes the state of the fix to :doc:`binary restart files <restart>`. This includes information about the random
number generator seed, the next timestep for MC exchanges, the number
of exchange attempts and successes etc. See
the :doc:`read_restart <read_restart>` command for info on how to
re-specify a fix in an input script that reads a restart file, so that
the operation of the fix continues in an uninterrupted fashion.
This fix writes the state of the fix to :doc:`binary restart files
<restart>`. This includes information about the random number
generator seed, the next timestep for MC exchanges, the number of
exchange attempts and successes etc. See the :doc:`read_restart
<read_restart>` command for info on how to re-specify a fix in an
input script that reads a restart file, so that the operation of the
fix continues in an uninterrupted fashion.
.. note::
@ -165,12 +166,13 @@ by various :doc:`output commands <Howto_output>`. The vector values are
the following global cumulative quantities:
* 1 = swap attempts
* 2 = swap successes
* 2 = swap accepts
The vector values calculated by this fix are "extensive".
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>`.
the :doc:`run <run>` command. This fix is not invoked during
:doc:`energy minimization <minimize>`.
Restrictions
""""""""""""
@ -184,7 +186,8 @@ Related commands
:doc:`fix nvt <fix_nh>`, :doc:`neighbor <neighbor>`,
:doc:`fix deposit <fix_deposit>`, :doc:`fix evaporate <fix_evaporate>`,
:doc:`delete_atoms <delete_atoms>`, :doc:`fix gcmc <fix_gcmc>`
:doc:`delete_atoms <delete_atoms>`, :doc:`fix gcmc <fix_gcmc>`,
:doc:`fix mol/swap <fix_mol_swap>`
Default
"""""""

18
doc/src/fix_bond_swap.rst
View File

@ -88,18 +88,18 @@ and bond partners B2 of B1 a is performed. For each pair of A1-A2 and
B1-B2 bonds to be eligible for swapping, the following 4 criteria must
be met:
(1) All 4 monomers must be in the fix group.
1. All 4 monomers must be in the fix group.
(2) All 4 monomers must be owned by the processor (not ghost atoms).
This insures that another processor does not attempt to swap bonds
involving the same atoms on the same timestep. Note that this also
means that bond pairs which straddle processor boundaries are not
eligible for swapping on this step.
2. All 4 monomers must be owned by the processor (not ghost atoms).
This insures that another processor does not attempt to swap bonds
involving the same atoms on the same timestep. Note that this also
means that bond pairs which straddle processor boundaries are not
eligible for swapping on this step.
(3) The distances between 4 pairs of atoms -- (A1,A2), (B1,B2),
(A1,B2), (B1,A2) -- must all be less than the specified *cutoff*\ .
3. The distances between 4 pairs of atoms -- (A1,A2), (B1,B2), (A1,B2),
(B1,A2) -- must all be less than the specified *cutoff*.
(4) The molecule IDs of A1 and B1 must be the same (see below).
4. The molecule IDs of A1 and B1 must be the same (see below).
If an eligible B1 partner is found, the energy change due to swapping
the 2 bonds is computed. This includes changes in pairwise, bond, and

5
doc/src/fix_brownian.rst
View File

@ -8,9 +8,8 @@ fix brownian command
fix brownian/sphere command
===========================
fix brownian/sphere command
===========================
fix brownian/asphere command
============================
Syntax
""""""

4
doc/src/fix_halt.rst
View File

@ -19,7 +19,7 @@ Syntax
bondmax = length of longest bond in the system (in length units)
tlimit = elapsed CPU time (in seconds)
diskfree = free disk space (in megabytes)
diskfree = free disk space (in MBytes)
v_name = name of :doc:`equal-style variable <variable>`
* operator = "<" or "<=" or ">" or ">=" or "==" or "!=" or "\|\^"
@ -81,7 +81,7 @@ the timer frequently across a large number of processors may be
non-negligible.
The *diskfree* attribute will check for available disk space (in
megabytes) on supported operating systems. By default it will
MBytes) on supported operating systems. By default it will
check the file system of the current working directory. This
can be changed with the optional *path* keyword, which will take
the path to a file or folder on the file system to be checked

25
doc/src/fix_langevin.rst
View File

@ -138,16 +138,18 @@ temperature with optional time-dependence as well.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. removing the center-of-mass velocity from a
group of atoms or removing the x-component of velocity from the
calculation. This is not done by default, but only if the
:doc:`fix_modify <fix_modify>` command is used to assign a temperature
compute to this fix that includes such a bias term. See the doc pages
for individual :doc:`compute commands <compute>` to determine which ones
include a bias. In this case, the thermostat works in the following
manner: bias is removed from each atom, thermostatting is performed on
the remaining thermal degrees of freedom, and the bias is added back
in.
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
The *damp* parameter is specified in time units and determines how
rapidly the temperature is relaxed. For example, a value of 100.0 means
@ -183,7 +185,8 @@ omega (which is derived from the angular momentum in the case of
aspherical particles).
The rotational temperature of the particles can be monitored by the
:doc:`compute temp/sphere <compute_temp_sphere>` and :doc:`compute temp/asphere <compute_temp_asphere>` commands with their rotate
:doc:`compute temp/sphere <compute_temp_sphere>` and :doc:`compute
temp/asphere <compute_temp_asphere>` commands with their rotate
options.
For the *omega* keyword there is also a scale factor of

25
doc/src/fix_langevin_drude.rst
View File

@ -167,17 +167,20 @@ functions, and include :doc:`thermo_style <thermo_style>` command
keywords for the simulation box parameters and timestep and elapsed
time. Thus it is easy to specify a time-dependent temperature.
Like other fixes that perform thermostatting, this fix can be used with
:doc:`compute commands <compute>` that remove a "bias" from the atom
velocities. E.g. removing the center-of-mass velocity from a group of
atoms. This is not done by default, but only if the
:doc:`fix_modify <fix_modify>` command is used to assign a temperature
compute to this fix that includes such a bias term. See the doc pages
for individual :doc:`compute commands <compute>` to determine which ones
include a bias. In this case, the thermostat works in the following
manner: bias is removed from each atom, thermostatting is performed on
the remaining thermal degrees of freedom, and the bias is added back
in. NOTE: this feature has not been tested.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
Note: The temperature thermostatting the core-Drude particle pairs
should be chosen low enough, so as to mimic as closely as possible the

170
doc/src/fix_mol_swap.rst Normal file
View File

@ -0,0 +1,170 @@
.. index:: fix mol/swap
fix mol/swap command
=====================
Syntax
""""""
.. parsed-literal::
fix ID group-ID mol/swap N X itype jtype seed T keyword value ...
* ID, group-ID are documented in :doc:`fix <fix>` command
* atom/swap = style name of this fix command
* N = invoke this fix every N steps
* X = number of swaps to attempt every N steps
* itype,jtype = two atom types to swap with each other
* seed = random # seed (positive integer)
* T = scaling temperature of the MC swaps (temperature units)
* zero or more keyword/value pairs may be appended to args
* keyword = *ke*
.. parsed-literal::
*ke* value = *no* or *yes*
*no* = no conservation of kinetic energy after atom swaps
*yes* = kinetic energy is conserved after atom swaps
Examples
""""""""
.. code-block:: LAMMPS
fix 2 all mol/swap 100 1 2 3 29494 300.0 ke no
fix mySwap fluid mol/swap 500 10 1 2 482798 1.0
Description
"""""""""""
This fix performs Monte Carlo swaps of two specified atom types within
a randomly selected molecule. Two possible use cases are as follows.
First, consider a mixture of some molecules with atoms of itype and
other molecules with atoms of jtype. The fix will select a random
molecule and attempt to swap all the itype atoms to jtype for the
first kind of molecule, or all the jtype atoms to itype for the second
kind. Because the swap will only take place if it is energetically
favorable, the fix can be used to determine the miscibility of 2
different kinds of molecules much more quickly than just dynamics
would do it.
Second, consider diblock co-polymers with two types of monomers itype
and jtype. The fix will select a random molecule and attempt to do a
itype <--> jtype swap of all those monomers within the molecule. Thus
the fix can be used to find the energetically favorable fractions of
two flavors of diblock co-polymers.
Intra-molecular swaps of atom types are attempted every N timesteps. On
that timestep, X swaps are attempted. For each attempt a single
molecule ID is randomly selected. The range of possible molecule IDs
from loID to hiID is pre-computed before each run begins. The
loID/hiID is set for the molecule with the smallest/largest ID which
has any itype or jtype atoms in it. Note that if you define a system
with many molecule IDs between loID and hiID which have no itype or
jtype atoms, then the fix will be inefficient at performing swaps.
Also note that if atoms with molecule ID = 0 exist, they are not
considered molecules by this fix; they are assumed to be solvent atoms
or molecules.
Candidate atoms for swapping must also be in the fix group. Atoms
within the selected molecule which are not itype or jtype are ignored.
When an atom is swapped from itype to jtype (or vice versa), if
charges are defined, the charge values for itype versus jtype atoms
are also swapped. This requires that all itype atoms in the system
have the same charge value. Likewise all jtype atoms in the system
must have the same charge value. If this is not the case, LAMMPS
issues a warning that it cannot swap charge values.
If the *ke* keyword is set to yes, which is the default, and the
masses of itype and jtype atoms are different, then when a swap
occurs, the velocity of the swapped atom is rescaled by the sqrt of
the mass ratio, so as to conserve the kinetic energy of the atom.
----------
The potential energy of the entire system is computed before and after
each swap is performed within a single molecule. The specified
temperature T is used in the Metropolis criterion to accept or reject
the attempted swap. If the swap is rejected all swapped values are
reversed.
The potential energy calculations can include systems and models with
the following features:
* manybody pair styles, including EAM
* hybrid pair styles
* long-range electrostatics (kspace)
* triclinic systems
* potential energy contributions from other fixes
For the last bullet point, fixes can have an associated potential
energy. Examples of such fixes include: :doc:`efield <fix_efield>`,
:doc:`gravity <fix_gravity>`, :doc:`addforce <fix_addforce>`,
:doc:`langevin <fix_langevin>`, :doc:`restrain <fix_restrain>`,
:doc:`temp/berendsen <fix_temp_berendsen>`, :doc:`temp/rescale
<fix_temp_rescale>`, and :doc:`wall fixes <fix_wall>`. For that
energy to be included in the total potential energy of the system (the
quantity used for the swap accept/reject decision), you MUST enable
the :doc:`fix_modify <fix_modify>` *energy* option for that fix. The
doc pages for individual :doc:`fix <fix>` commands specify if this
should be done.
.. note::
One comment on computational efficiency. If the cutoff lengths
defined for the pair style are different for itype versus jtype
atoms (for any of their interactions with any other atom type), then
a new neighbor list needs to be generated for every attempted swap.
This is potentially expensive if N is small or X is large.
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
This fix writes the state of the fix to :doc:`binary restart files
<restart>`. This includes information about the random number
generator seed, the next timestep for MC exchanges, the number of
exchange attempts and successes etc. See the :doc:`read_restart
<read_restart>` command for info on how to re-specify a fix in an
input script that reads a restart file, so that the operation of the
fix continues in an uninterrupted fashion.
.. note::
For this to work correctly, the timestep must **not** be changed
after reading the restart with :doc:`reset_timestep <reset_timestep>`.
The fix will try to detect it and stop with an error.
None of the :doc:`fix_modify <fix_modify>` options are relevant to this
fix.
This fix computes a global vector of length 2, which can be accessed
by various :doc:`output commands <Howto_output>`. The vector values are
the following global cumulative quantities:
* 1 = swap attempts
* 2 = swap accepts
The vector values calculated by this fix are "extensive".
No parameter of this fix can be used with the *start/stop* keywords of
the :doc:`run <run>` command. This fix is not invoked during
:doc:`energy minimization <minimize>`.
Restrictions
""""""""""""
This fix is part of the MC package. It is only enabled if LAMMPS was
built with that package. See the :doc:`Build package <Build_package>`
doc page for more info.
Related commands
""""""""""""""""
:doc:`fix atom/swap <fix_atom_swap>`, :doc:`fix gcmc <fix_gcmc>`
Default
"""""""
The option default is ke = yes.

27
doc/src/fix_nh.rst
View File

@ -486,19 +486,20 @@ temperature or pressure during thermodynamic output via the
compute-ID. It also means that changing attributes of *thermo_temp*
or *thermo_press* will have no effect on this fix.
Like other fixes that perform thermostatting, fix nvt and fix npt can
be used with :doc:`compute commands <compute>` that calculate a
temperature after removing a "bias" from the atom velocities.
E.g. removing the center-of-mass velocity from a group of atoms or
only calculating temperature on the x-component of velocity or only
calculating temperature for atoms in a geometric region. This is not
done by default, but only if the :doc:`fix_modify <fix_modify>` command
is used to assign a temperature compute to this fix that includes such
a bias term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
----------

30
doc/src/fix_npt_asphere.rst
View File

@ -48,8 +48,9 @@ can also have a bias velocity removed from them before thermostatting
takes place; see the description below.
Additional parameters affecting the thermostat and barostat are
specified by keywords and values documented with the :doc:`fix npt <fix_nh>` command. See, for example, discussion of the *temp*,
*iso*, *aniso*, and *dilate* keywords.
specified by keywords and values documented with the :doc:`fix npt
<fix_nh>` command. See, for example, discussion of the *temp*, *iso*,
*aniso*, and *dilate* keywords.
The particles in the fix group are the only ones whose velocities and
positions are updated by the velocity/position update portion of the
@ -89,18 +90,19 @@ It also means that changing attributes of *thermo_temp* or
*thermo_press* will have no effect on this fix.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that calculate a temperature
after removing a "bias" from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the :doc:`fix_modify <fix_modify>` command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
----------

25
doc/src/fix_npt_body.rst
View File

@ -87,18 +87,19 @@ It also means that changing attributes of *thermo_temp* or
*thermo_press* will have no effect on this fix.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that calculate a temperature
after removing a "bias" from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the :doc:`fix_modify <fix_modify>` command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
----------

27
doc/src/fix_npt_cauchy.rst
View File

@ -400,19 +400,20 @@ temperature or pressure during thermodynamic output via the
compute-ID. It also means that changing attributes of *thermo_temp*
or *thermo_press* will have no effect on this fix.
Like other fixes that perform thermostatting, fix npt/cauchy can
be used with :doc:`compute commands <compute>` that calculate a
temperature after removing a "bias" from the atom velocities.
E.g. removing the center-of-mass velocity from a group of atoms or
only calculating temperature on the x-component of velocity or only
calculating temperature for atoms in a geometric region. This is not
done by default, but only if the :doc:`fix_modify <fix_modify>` command
is used to assign a temperature compute to this fix that includes such
a bias term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
----------

25
doc/src/fix_npt_sphere.rst
View File

@ -103,18 +103,19 @@ appropriate compute-ID. It also means that changing attributes of
*thermo_temp* or *thermo_press* will have no effect on this fix.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that calculate a temperature
after removing a "bias" from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the :doc:`fix_modify <fix_modify>` command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
----------

25
doc/src/fix_nvt_asphere.rst
View File

@ -72,18 +72,19 @@ It also means that changing attributes of *thermo_temp* will have no
effect on this fix.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that calculate a temperature
after removing a "bias" from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the :doc:`fix_modify <fix_modify>` command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
----------

25
doc/src/fix_nvt_body.rst
View File

@ -69,18 +69,19 @@ It also means that changing attributes of *thermo_temp* will have no
effect on this fix.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that calculate a temperature
after removing a "bias" from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the :doc:`fix_modify <fix_modify>` command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
----------

74
doc/src/fix_nvt_sllod.rst
View File

@ -37,15 +37,16 @@ trajectory consistent with the canonical ensemble.
This thermostat is used for a simulation box that is changing size
and/or shape, for example in a non-equilibrium MD (NEMD) simulation.
The size/shape change is induced by use of the :doc:`fix deform <fix_deform>` command, so each point in the simulation box
can be thought of as having a "streaming" velocity. This
position-dependent streaming velocity is subtracted from each atom's
actual velocity to yield a thermal velocity which is used for
temperature computation and thermostatting. For example, if the box
is being sheared in x, relative to y, then points at the bottom of the
box (low y) have a small x velocity, while points at the top of the
box (hi y) have a large x velocity. These velocities do not
contribute to the thermal "temperature" of the atom.
The size/shape change is induced by use of the :doc:`fix deform
<fix_deform>` command, so each point in the simulation box can be
thought of as having a "streaming" velocity. This position-dependent
streaming velocity is subtracted from each atom's actual velocity to
yield a thermal velocity which is used for temperature computation and
thermostatting. For example, if the box is being sheared in x,
relative to y, then points at the bottom of the box (low y) have a
small x velocity, while points at the top of the box (hi y) have a
large x velocity. These velocities do not contribute to the thermal
"temperature" of the atom.
.. note::
@ -60,13 +61,15 @@ contribute to the thermal "temperature" of the atom.
consistent.
The SLLOD equations of motion, originally proposed by Hoover and Ladd
(see :ref:`(Evans and Morriss) <Evans3>`), were proven to be equivalent to
Newton's equations of motion for shear flow by :ref:`(Evans and Morriss) <Evans3>`. They were later shown to generate the desired
velocity gradient and the correct production of work by stresses for
all forms of homogeneous flow by :ref:`(Daivis and Todd) <Daivis>`. As
implemented in LAMMPS, they are coupled to a Nose/Hoover chain
thermostat in a velocity Verlet formulation, closely following the
implementation used for the :doc:`fix nvt <fix_nh>` command.
(see :ref:`(Evans and Morriss) <Evans3>`), were proven to be
equivalent to Newton's equations of motion for shear flow by
:ref:`(Evans and Morriss) <Evans3>`. They were later shown to generate
the desired velocity gradient and the correct production of work by
stresses for all forms of homogeneous flow by :ref:`(Daivis and Todd)
<Daivis>`. As implemented in LAMMPS, they are coupled to a
Nose/Hoover chain thermostat in a velocity Verlet formulation, closely
following the implementation used for the :doc:`fix nvt <fix_nh>`
command.
.. note::
@ -94,27 +97,28 @@ underscore + "temp", and the group for the new compute is the same as
the fix group.
Note that this is NOT the compute used by thermodynamic output (see
the :doc:`thermo_style <thermo_style>` command) with ID = *thermo_temp*.
This means you can change the attributes of this fix's temperature
(e.g. its degrees-of-freedom) via the
:doc:`compute_modify <compute_modify>` command or print this temperature
during thermodynamic output via the :doc:`thermo_style custom <thermo_style>` command using the appropriate compute-ID.
It also means that changing attributes of *thermo_temp* will have no
effect on this fix.
the :doc:`thermo_style <thermo_style>` command) with ID =
*thermo_temp*. This means you can change the attributes of this fix's
temperature (e.g. its degrees-of-freedom) via the :doc:`compute_modify
<compute_modify>` command or print this temperature during
thermodynamic output via the :doc:`thermo_style custom <thermo_style>`
command using the appropriate compute-ID. It also means that changing
attributes of *thermo_temp* will have no effect on this fix.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that calculate a temperature
after removing a "bias" from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the :doc:`fix_modify <fix_modify>` command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
----------

25
doc/src/fix_nvt_sphere.rst
View File

@ -86,18 +86,19 @@ It also means that changing attributes of *thermo_temp* will have no
effect on this fix.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that calculate a temperature
after removing a "bias" from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the :doc:`fix_modify <fix_modify>` command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
----------

5
doc/src/fix_qeq.rst
View File

@ -230,7 +230,10 @@ These fixes are part of the QEQ package. They are only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
The qeq fixes are not compatible with the GPU and USER-INTEL packages.
These qeq fixes are not compatible with the GPU and USER-INTEL packages.
These qeq fixes will ignore electric field contributions from
:doc:`fix efield <fix_efield>`.
Related commands
""""""""""""""""

6
doc/src/fix_qeq_reaxff.rst
View File

@ -116,6 +116,12 @@ 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 10 angstroms.
This fix may be used in combination with :doc:`fix efield <fix_efield>`
and will apply the external electric field during charge equilibration,
but there may be only one fix efield instance used, it may only use a
constant electric field, and the electric field vector may only have
components in non-periodic directions.
Related commands
""""""""""""""""

2
doc/src/fix_qtb.rst
View File

@ -128,7 +128,7 @@ spectrum while consumes more memory. With fixed *f_max* and
:math:`\gamma`, *N_f* should be big enough to converge the classical
temperature :math:`T^{cl}` as a function of target quantum bath
temperature. Memory usage per processor could be from 10 to 100
Mbytes.
MBytes.
.. note::

11
doc/src/fix_reaxff_species.rst
View File

@ -56,6 +56,17 @@ number of molecules of each species. In this context, "species" means
a unique molecule. The chemical formula of each species is given in
the first line.
.. warning::
In order to compute averaged data, it is required that there are no
neighbor list rebuilds between the *Nfreq* steps. For that reason, fix
*reaxff/species* may change your neighbor list settings. There will
be a warning message showing the new settings. Having an *Nfreq*
setting that is larger than what is required for correct computation
of the ReaxFF force field interactions can thus lead to incorrect
results. For typical ReaxFF calculations a value of 100 is already
quite large.
If the filename ends with ".gz", the output file is written in gzipped
format. A gzipped dump file will be about 3x smaller than the text version,
but will also take longer to write.

5
doc/src/fix_saed_vtk.rst
View File

@ -28,7 +28,6 @@ Syntax
Nstart = start averaging on this timestep
*file* arg = filename
filename = name of file to output time averages to
*overwrite* arg = none = overwrite output file with only latest output
Examples
""""""""
@ -161,10 +160,6 @@ the *file* keyword and this string is appended with _N.vtk where N is
an index (0,1,2...) to account for situations with multiple diffraction
intensity outputs.
The *overwrite* keyword will continuously overwrite the output file
with the latest output, so that it only contains one timestep worth of
output. This option can only be used with the *ave running* setting.
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

23
doc/src/fix_setforce.rst
View File

@ -89,26 +89,13 @@ precession vectors instead of the forces.
----------
Styles with a *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed on the :doc:`Speed packages <Speed_packages>` doc
page. The accelerated styles take the same arguments and should
produce the same results, except for round-off and precision issues.
.. include:: accel_styles.rst
The region keyword is also supported by Kokkos, but a Kokkos-enabled
region must be used. See the region :doc:`region <region>` command for
more information.
.. note::
These accelerated styles are part of the r Kokkos package. They are
only enabled if LAMMPS was built with that package. See the :doc:`Build package <Build_package>` page for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :doc:`-suffix command-line switch <Run_options>` when you invoke LAMMPS, or you can use the
:doc:`suffix <suffix>` command in your input script.
See the :doc:`Speed packages <Speed_packages>` page for more
instructions on how to use the accelerated styles effectively.
The region keyword is supported by Kokkos, but a Kokkos-enabled
region must be used. See the region :doc:`region <region>` command for
more information.
----------

25
doc/src/fix_temp_berendsen.rst
View File

@ -102,18 +102,19 @@ It also means that changing attributes of *thermo_temp* will have no
effect on this fix.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that calculate a temperature
after removing a "bias" from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the :doc:`fix_modify <fix_modify>` command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
----------

41
doc/src/fix_temp_csvr.rst
View File

@ -110,28 +110,29 @@ during thermodynamic output via the :doc:`thermo_style custom <thermo_style>` co
It also means that changing attributes of *thermo_temp* will have no
effect on this fix.
Like other fixes that perform thermostatting, these fixes can be used
with :doc:`compute commands <compute>` that calculate a temperature
after removing a "bias" from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the :doc:`fix_modify <fix_modify>` command is used
to assign a temperature compute to this fix that includes such a bias
term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal degrees of freedom, and the bias is added back in.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
An important feature of these thermostats is that they have an
associated effective energy that is a constant of motion.
The effective energy is the total energy (kinetic + potential) plus
the accumulated kinetic energy changes due to the thermostat. The
latter quantity is the global scalar computed by these fixes. This
feature is useful to check the integration of the equations of motion
against discretization errors. In other words, the conservation of
the effective energy can be used to choose an appropriate integration
associated effective energy that is a constant of motion. The
effective energy is the total energy (kinetic + potential) plus the
accumulated kinetic energy changes due to the thermostat. The latter
quantity is the global scalar computed by these fixes. This feature is
useful to check the integration of the equations of motion against
discretization errors. In other words, the conservation of the
effective energy can be used to choose an appropriate integration
:doc:`timestep <timestep>`. This is similar to the usual paradigm of
checking the conservation of the total energy in the microcanonical
ensemble.

26
doc/src/fix_temp_rescale.rst
View File

@ -109,19 +109,19 @@ command using the appropriate compute-ID. It also means that changing
attributes of *thermo_temp* will have no effect on this fix.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that calculate a temperature
after removing a "bias" from the atom velocities. E.g. removing the
center-of-mass velocity from a group of atoms or only calculating
temperature on the x-component of velocity or only calculating
temperature for atoms in a geometric region. This is not done by
default, but only if the :doc:`fix_modify <fix_modify>` command is
used to assign a temperature compute to this fix that includes such a
bias term. See the doc pages for individual :doc:`compute commands
<compute>` to determine which ones include a bias. In this case, the
thermostat works in the following manner: the current temperature is
calculated taking the bias into account, bias is removed from each
atom, thermostatting is performed on the remaining thermal degrees of
freedom, and the bias is added back in.
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
----------

40
doc/src/fix_tgnh_drude.rst
View File

@ -187,26 +187,32 @@ barostatting.
----------
Like other fixes that perform thermostatting, these fixes can
be used with :doc:`compute commands <compute>` that calculate a
temperature after removing a "bias" from the atom velocities.
This is not done by default, but only if the :doc:`fix_modify <fix_modify>` command
is used to assign a temperature compute to this fix that includes such
a bias term. See the doc pages for individual :doc:`compute commands <compute>` to determine which ones include a bias. In
this case, the thermostat works in the following manner: the current
temperature is calculated taking the bias into account, bias is
removed from each atom, thermostatting is performed on the remaining
thermal DOF, and the bias is added back in.
Like other fixes that perform thermostatting, this fix can be used
with :doc:`compute commands <compute>` that remove a "bias" from the
atom velocities. E.g. to apply the thermostat only to atoms within a
spatial :doc:`region <region>`, or to remove the center-of-mass
velocity from a group of atoms, or to remove the x-component of
velocity from the calculation.
This is not done by default, but only if the :doc:`fix_modify
<fix_modify>` command is used to assign a temperature compute to this
fix that includes such a bias term. See the doc pages for individual
:doc:`compute temp commands <compute>` to determine which ones include
a bias. In this case, the thermostat works in the following manner:
bias is removed from each atom, thermostatting is performed on the
remaining thermal degrees of freedom, and the bias is added back in.
.. note::
However, not all temperature compute commands are valid to be used with these fixes.
Precisely, only temperature compute that does not modify the DOF of the group can be used.
E.g. :doc:`compute temp/ramp <compute_temp_ramp>` and :doc:`compute viscosity/cos <compute_viscosity_cos>`
compute the kinetic energy after remove a velocity gradient without affecting the DOF of the group,
then they can be invoked in this way.
In contrast, :doc:`compute temp/partial <compute_temp_partial>` may remove the DOF at one or more dimensions,
therefore it cannot be used with these fixes.
However, not all temperature compute commands are valid to be used
with these fixes. Precisely, only temperature compute that does
not modify the DOF of the group can be used. E.g. :doc:`compute
temp/ramp <compute_temp_ramp>` and :doc:`compute viscosity/cos
<compute_viscosity_cos>` compute the kinetic energy after remove a
velocity gradient without affecting the DOF of the group, then they
can be invoked in this way. In contrast, :doc:`compute
temp/partial <compute_temp_partial>` may remove the DOF at one or
more dimensions, therefore it cannot be used with these fixes.
----------

249
doc/src/fix_ttm.rst
View File

@ -1,9 +1,13 @@
.. index:: fix ttm
.. index:: fix ttm/grid
.. index:: fix ttm/mod
fix ttm command
===============
fix ttm/grid command
====================
fix ttm/mod command
===================
@ -12,13 +16,13 @@ Syntax
.. parsed-literal::
fix ID group-ID ttm seed C_e rho_e kappa_e gamma_p gamma_s v_0 Nx Ny Nz T_infile N T_outfile
fix ID group-ID ttm/mod seed init_file Nx Ny Nz T_infile N T_outfile
fix ID group-ID ttm seed C_e rho_e kappa_e gamma_p gamma_s v_0 Nx Ny Nz keyword value ...
fix ID group-ID ttm/mod seed init_file Nx Ny Nz keyword value ...
* ID, group-ID are documented in :doc:`fix <fix>` command
* style = *ttm* or *ttm_mod*
* style = *ttm* or *ttm/grid* or *ttm/mod*
* seed = random number seed to use for white noise (positive integer)
* remaining arguments for fix ttm:
* remaining arguments for fix ttm or fix ttm/grid
.. parsed-literal::
@ -31,9 +35,6 @@ Syntax
Nx = number of thermal solve grid points in the x-direction (positive integer)
Ny = number of thermal solve grid points in the y-direction (positive integer)
Nz = number of thermal solve grid points in the z-direction (positive integer)
T_infile = filename to read initial electronic temperature from
N = dump TTM temperatures every this many timesteps, 0 = no dump
T_outfile = filename to write TTM temperatures to (only needed if N > 0)
* remaining arguments for fix ttm/mod:
@ -43,18 +44,29 @@ Syntax
Nx = number of thermal solve grid points in the x-direction (positive integer)
Ny = number of thermal solve grid points in the y-direction (positive integer)
Nz = number of thermal solve grid points in the z-direction (positive integer)
T_infile = filename to read initial electronic temperature from
N = dump TTM temperatures every this many timesteps, 0 = no dump
T_outfile = filename to write TTM temperatures to (only needed if N > 0)
* zero or more keyword/value(s) pairs may be appended
* keyword = *set* or *infile* or *outfile*
.. parsed-literal::
*set* value = Tinit
Tinit = initial electronic temperature at all grid points (temperature units)
*infile* value = file.in with grid values for electronic temperatures
*outfile* values = Nout file.out
Nout = dump grid temperatures every this many timesteps
file.out = filename to write grid temperatures to
Examples
""""""""
.. code-block:: LAMMPS
fix 2 all ttm 699489 1.0 1.0 10 0.1 0.0 2.0 1 12 1 initialTs 1000 T.out
fix 2 all ttm 123456 1.0 1.0 1.0 1.0 1.0 5.0 5 5 5 Te.in 1 Te.out
fix 2 all ttm/mod 34277 parameters.txt 5 5 5 T_init 10 T_out
fix 2 all ttm 699489 1.0 1.0 10 0.1 0.0 2.0 1 12 1 infile initial outfile 1000 T.out
fix 3 all ttm/grid 123456 1.0 1.0 1.0 1.0 1.0 5.0 5 5 5 infile Te.in
fix 4 all ttm/mod 34277 parameters.txt 5 5 5 infile T_init outfile 10 T_out
Example input scripts using these commands can be found in examples/ttm.
Description
"""""""""""
@ -62,36 +74,48 @@ Description
Use a two-temperature model (TTM) to represent heat transfer through
and between electronic and atomic subsystems. LAMMPS models the
atomic subsystem as usual with a molecular dynamics model and the
classical force field specified by the user, but the electronic
subsystem is modeled as a continuum, or a background "gas", on a
regular grid. Energy can be transferred spatially within the grid
representing the electrons. Energy can also be transferred between
the electronic and the atomic subsystems. The algorithm underlying
this fix was derived by D. M. Duffy and A. M. Rutherford and is
discussed in two J Physics: Condensed Matter papers: :ref:`(Duffy) <Duffy>`
and :ref:`(Rutherford) <Rutherford>`. They used this algorithm in cascade
simulations where a primary knock-on atom (PKA) was initialized with a
high velocity to simulate a radiation event.
classical force field specified by the user. The electronic subsystem
is modeled as a continuum, or a background "gas", on a regular grid
which overlays the simulation domain. Energy can be transferred
spatially within the grid representing the electrons. Energy can also
be transferred between the electronic and atomic subsystems. The
algorithm underlying this fix was derived by D. M. Duffy
and A. M. Rutherford and is discussed in two J Physics: Condensed
Matter papers: :ref:`(Duffy) <Duffy>` and :ref:`(Rutherford)
<Rutherford>`. They used this algorithm in cascade simulations where
a primary knock-on atom (PKA) was initialized with a high velocity to
simulate a radiation event.
The description in this sub-section applies to both fix ttm and fix
ttm/mod. Fix ttm/mod adds options to account for external heat
sources (e.g. at a surface) and for specifying parameters that allow
the electronic heat capacity to depend strongly on electronic
temperature. It is more expensive computationally than fix ttm
because it treats the thermal diffusion equation as non-linear. More
details on fix ttm/mod are given below.
The description in this sub-section applies to all 3 fix styles:
*ttm*, *ttm/grid*, and *ttm/mod*.
Fix *ttm/grid* distributes the regular grid across processors consistent
with the sub-domains of atoms owned by each processor, but is otherwise
identical to fix ttm. Note that fix *ttm* stores a copy of the grid on
each processor, which is acceptable when the overall grid is reasonably
small. For larger grids you should use fix *ttm/grid* instead.
Fix *ttm/mod* adds options to account for external heat sources (e.g. at
a surface) and for specifying parameters that allow the electronic
heat capacity to depend strongly on electronic temperature. It is
more expensive computationally than fix *ttm* because it treats the
thermal diffusion equation as non-linear. More details on fix *ttm/mod*
are given below.
Heat transfer between the electronic and atomic subsystems is carried
out via an inhomogeneous Langevin thermostat. This thermostat differs
from the regular Langevin thermostat (:doc:`fix langevin <fix_langevin>`) in three important ways. First, the
Langevin thermostat is applied uniformly to all atoms in the
out via an inhomogeneous Langevin thermostat. Only atoms in the fix
group contribute to and are affected by this heat transfer.
This thermostatting differs from the regular Langevin thermostat
(:doc:`fix langevin <fix_langevin>`) in three important ways. First,
the Langevin thermostat is applied uniformly to all atoms in the
user-specified group for a single target temperature, whereas the TTM
fix applies Langevin thermostatting locally to atoms within the
fixes apply Langevin thermostatting locally to atoms within the
volumes represented by the user-specified grid points with a target
temperature specific to that grid point. Second, the Langevin
thermostat couples the temperature of the atoms to an infinite heat
reservoir, whereas the heat reservoir for fix TTM is finite and
represents the local electrons. Third, the TTM fix allows users to
reservoir, whereas the heat reservoir for the TTM fixes is finite and
represents the local electrons. Third, the TTM fixes allow users to
specify not just one friction coefficient, but rather two independent
friction coefficients: one for the electron-ion interactions
(*gamma_p*), and one for electron stopping (*gamma_s*).
@ -123,29 +147,59 @@ as that in equation 6 of :ref:`(Duffy) <Duffy>`, with the exception that the
electronic density is explicitly represented, rather than being part
of the specific heat parameter.
Currently, fix ttm assumes that none of the user-supplied parameters
will vary with temperature. Note that :ref:`(Duffy) <Duffy>` used a tanh()
functional form for the temperature dependence of the electronic
specific heat, but ignored temperature dependencies of any of the
other parameters. See more discussion below for fix ttm/mod.
Currently, the TTM fixes assume that none of the user-supplied
parameters will vary with temperature. Note that :ref:`(Duffy)
<Duffy>` used a tanh() functional form for the temperature dependence
of the electronic specific heat, but ignored temperature dependencies
of any of the other parameters. See more discussion below for fix
ttm/mod.
These fixes require use of periodic boundary conditions and a 3D
simulation. Periodic boundary conditions are also used in the heat
equation solve for the electronic subsystem. This varies from the
approach of :ref:`(Rutherford) <Rutherford>` where the atomic subsystem was
..note::
These fixes do not perform time integration of the atoms in the fix
group, they only rescale their velocities. Thus a time integration
fix such as :doc:`fix nve <fix_nve>` should be used in conjunction
with these fixes. These fixes should not normally be used on atoms
that have their temperature controlled by another thermostatting
fix, e.g. :doc:`fix nvt <fix_nh>` or :doc:`fix langevin
<fix_langevin>`.
..note::
These fixes require use of an orthogonal 3d simulation box with
periodic boundary conditions in all dimensions. They also require
that the size and shape of the simulation box do not vary
dynamically, e.g. due to use of the :doc:`fix npt <fix_nh>` command.
Likewise, the size/shape of processor sub-domains cannot vary due to
dynamic load-balancing via use of the :doc:`fix balance
<fix_balance>` command. It is possible however to load balance
before the simulation starts using the :doc:`balance <balance>`
command, so that each processor has a different size sub-domain.
Periodic boundary conditions are also used in the heat equation solve
for the electronic subsystem. This varies from the approach of
:ref:`(Rutherford) <Rutherford>` where the atomic subsystem was
embedded within a larger continuum representation of the electronic
subsystem.
The initial electronic temperature input file, *T_infile*, is a text
file LAMMPS reads in with no header and with four numeric columns
(ix,iy,iz,Temp) and with a number of rows equal to the number of
user-specified grid points (Nx by Ny by Nz). The ix,iy,iz are node
indices from 0 to nxnodes-1, etc. For example, the initial electronic
temperatures on a 1 by 2 by 3 grid could be specified in a *T_infile*
as follows:
The *set* keyword specifies a *Tinit* temperature value to initialize
the value stored on all grid points.
The *infile* keyword specifies an input file of electronic temperatures
for each grid point to be read in to initialize the grid. By default
the temperatures are all zero when the grid is created. The input file
is a text file which may have comments starting with the '#' character.
Each line contains four numeric columns: ix,iy,iz,Temperature. Empty
or comment-only lines will be ignored. The
number of lines must be equal to the number of user-specified grid
points (Nx by Ny by Nz). The ix,iy,iz are grid point indices ranging
from 0 to nxnodes-1 inclusive in each dimension. The lines can appear
in any order. For example, the initial electronic temperatures on a 1
by 2 by 3 grid could be specified in the file as follows:
.. parsed-literal::
# UNITS: metal COMMENT: initial electron temperature
0 0 0 1.0
0 0 1 1.0
0 0 2 1.0
@ -155,40 +209,37 @@ as follows:
where the electronic temperatures along the y=0 plane have been set to
1.0, and the electronic temperatures along the y=1 plane have been set
to 2.0. The order of lines in this file is no important. If all the
nodal values are not specified, LAMMPS will generate an error.
to 2.0. If all the grid point values are not specified, LAMMPS will
generate an error. LAMMPS will check if a "UNITS:" tag is in the first
line and stop with an error, if there is a mismatch with the current
units used.
The temperature output file, *T_oufile*, is created and written by
this fix. Temperatures for both the electronic and atomic subsystems
at every node and every N timesteps are output. If N is specified as
zero, no output is generated, and no output filename is needed. The
format of the output is as follows. One long line is written every
output timestep. The timestep itself is given in the first column.
The next Nx\*Ny\*Nz columns contain the temperatures for the atomic
subsystem, and the final Nx\*Ny\*Nz columns contain the temperatures for
the electronic subsystem. The ordering of the Nx\*Ny\*Nz columns is
with the z index varying fastest, y the next fastest, and x the
slowest.
..note::
These fixes do not change the coordinates of their atoms; they only
scales their velocities. Thus a time integration fix (e.g. :doc:`fix nve <fix_nve>`) should still be used to time integrate the affected
atoms. The fixes should not normally be used on atoms that have their
temperature controlled by another fix - e.g. :doc:`fix nvt <fix_nh>` or
:doc:`fix langevin <fix_langevin>`.
The electronic temperature at each grid point must be a non-zero
positive value, both initially, and as the temperature evovles over
time. Thus you must use either the *set* or *infile* keyword or be
restarting a simulation that used this fix previously.
.. note::
The *outfile* keyword has 2 values. The first value *Nout* triggers
output of the electronic temperatures for each grid point every Nout
timesteps. The second value is the filename for output which will
be suffixed by the timestep. The format of each output file is exactly
the same as the input temperature file. It will contain a comment in
the first line reporting the date the file was created, the LAMMPS
units setting in use, grid size and the current timestep.
The current implementations of these fixes create a copy of the
electron grid that overlays the entire simulation domain, for each
processor. Values on the grid are summed across all processors. Thus
you should insure that this grid is not too large, else your
simulation could incur high memory and communication costs.
Note that the atomic temperature for atoms in each grid cell can also
be computed and output by the :doc:`fix ave/chunk <fix_ave_chunk>`
command using the :doc:`compute chunk/atom <compute_chunk_atom>`
command to create a 3d array of chunks consistent with the grid used
by this fix.
----------
**Additional details for fix ttm/mod**
Fix ttm/mod uses the heat diffusion equation with possible external
Fix *ttm/mod* uses the heat diffusion equation with possible external
heat sources (e.g. laser heating in ablation simulations):
.. math::
@ -222,7 +273,8 @@ acting on an ion is:
.. math::
{\vec F}_i = - \partial U / \partial {\vec r}_i + {\vec F}_{langevin} - \nabla P_e/n_{ion}
{\vec F}_i = - \partial U / \partial {\vec r}_i + {\vec
F}_{langevin} - \nabla P_e/n_{ion}
where F_langevin is a force from Langevin thermostat simulating
electron-phonon coupling, and nabla P_e/n_ion is the electron blast
@ -246,7 +298,9 @@ is calculated as
.. math::
\nabla_x P_e = \left[\frac{C_e{}T_e(x)\lambda}{(x+\lambda)^2} + \frac{x}{x+\lambda}\frac{(C_e{}T_e)_{x+\Delta x}-(C_e{}T_e)_{x}}{\Delta x} \right]
\nabla_x P_e = \left[\frac{C_e{}T_e(x)\lambda}{(x+\lambda)^2} +
\frac{x}{x+\lambda}\frac{(C_e{}T_e)_{x+\Delta
x}-(C_e{}T_e)_{x}}{\Delta x} \right]
where lambda is the electron mean free path (see :ref:`(Norman) <Norman>`,
:ref:`(Pisarev) <Pisarev>`)
@ -286,10 +340,12 @@ Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
These fixes write the state of the electronic subsystem and the energy
exchange between the subsystems to :doc:`binary restart files <restart>`. See the :doc:`read_restart <read_restart>` command
for info on how to re-specify a fix in an input script that reads a
exchange between the subsystems to :doc:`binary restart files
<restart>`. See the :doc:`read_restart <read_restart>` command for
info on how to re-specify a fix in an input script that reads a
restart file, so that the operation of the fix continues in an
uninterrupted fashion.
uninterrupted fashion. Note that the restart script must define the
same size grid as the original script.
Because the state of the random number generator is not saved in the
restart files, this means you cannot do "exact" restarts with this
@ -297,16 +353,16 @@ fix, where the simulation continues on the same as if no restart had
taken place. However, in a statistical sense, a restarted simulation
should produce the same behavior.
None of the :doc:`fix_modify <fix_modify>` options are relevant to these
fixes.
None of the :doc:`fix_modify <fix_modify>` options are relevant to
these fixes.
Both fixes compute 2 output quantities stored in a vector of length 2,
which can be accessed by various :doc:`output commands <Howto_output>`.
The first quantity is the total energy of the electronic
subsystem. The second quantity is the energy transferred from the
electronic to the atomic subsystem on that timestep. Note that the
velocity verlet integrator applies the fix ttm forces to the atomic
subsystem as two half-step velocity updates: one on the current
These fixes compute 2 output quantities stored in a vector of length
2, which can be accessed by various :doc:`output commands
<Howto_output>`. The first quantity is the total energy of the
electronic subsystem. The second quantity is the energy transferred
from the electronic to the atomic subsystem on that timestep. Note
that the velocity verlet integrator applies the fix ttm forces to the
atomic subsystem as two half-step velocity updates: one on the current
timestep and one on the subsequent timestep. Consequently, the change
in the atomic subsystem energy is lagged by half a timestep relative
to the change in the electronic subsystem energy. As a result of this,
@ -322,13 +378,12 @@ of the :doc:`run <run>` command. The fixes are not invoked during
Restrictions
""""""""""""
Fix *ttm* and *ttm/mod* are part of the EXTRA-FIX package. They are
only enabled if LAMMPS was built with that package.
See the :doc:`Build package <Build_package>` page for more info.
All these fixes are part of the EXTRA-FIX package. They are only
enabled if LAMMPS was built with that package. See the :doc:`Build
package <Build_package>` page for more info.
These fixes can only be used for 3d simulations and orthogonal
simulation boxes. You must also use periodic
:doc:`boundary <boundary>` conditions.
As mentioned above, these fixes require 3d simulations and orthogonal
simulation boxes periodic in all 3 dimensions.
Related commands
""""""""""""""""

2
doc/src/fix_wall_gran_region.rst
View File

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

2
doc/src/group.rst
View File

@ -38,7 +38,7 @@ Syntax
*intersect* args = two or more group IDs
*dynamic* args = parent-ID keyword value ...
one or more keyword/value pairs may be appended
keyword = *region* or *var* or *every*
keyword = *region* or *var* or *property* or *every*
*region* value = region-ID
*var* value = name of variable
*property* value = name of custom integer or floating point vector

BIN
doc/src/img/decomp-balance.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 129 KiB

BIN
doc/src/img/decomp-processors.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 121 KiB

BIN
doc/src/img/decomp-rcb.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 121 KiB

BIN
doc/src/img/decomp-regular.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 121 KiB

BIN
doc/src/img/domain-decomp.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 547 KiB

BIN
doc/src/img/fft-decomp-parallel.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 35 KiB

BIN
doc/src/img/ghost-comm.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 33 KiB

BIN
doc/src/img/neigh-stencil.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 53 KiB

20
doc/src/improper_harmonic.rst
View File

@ -64,25 +64,7 @@ radian\^2.
----------
Styles with a *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed on the :doc:`Speed packages <Speed_packages>` doc
page. The accelerated styles take the same arguments and should
produce the same results, except for round-off and precision issues.
These accelerated styles are part of the GPU, INTEL, KOKKOS,
OPENMP and OPT packages, respectively. They are only enabled if
LAMMPS was built with those packages. See the :doc:`Build package
<Build_package>` page for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :doc:`-suffix
command-line switch <Run_options>` when you invoke LAMMPS, or you can
use the :doc:`suffix <suffix>` command in your input script.
See the :doc:`Speed packages <Speed_packages>` page for more
instructions on how to use the accelerated styles effectively.
.. include:: accel_styles.rst
----------

39
doc/src/kspace_style.rst
View File

@ -414,33 +414,26 @@ relative RMS error.
----------
Styles with a *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed on the :doc:`Speed packages <Speed_packages>` doc
page. The accelerated styles take the same arguments and should
produce the same results, except for round-off and precision issues.
.. include:: accel_styles.rst
More specifically, the *pppm/gpu* style performs charge assignment and
force interpolation calculations on the GPU. These processes are
performed either in single or double precision, depending on whether
the -DFFT_SINGLE setting was specified in your low-level Makefile, as
discussed above. The FFTs themselves are still calculated on the CPU.
If *pppm/gpu* is used with a GPU-enabled pair style, part of the PPPM
calculation can be performed concurrently on the GPU while other
calculations for non-bonded and bonded force calculation are performed
on the CPU.
.. note::
The *pppm/kk* style performs charge assignment and force interpolation
calculations, along with the FFTs themselves, on the GPU or (optionally) threaded
on the CPU when using OpenMP and FFTW3.
For the GPU package, the *pppm/gpu* style performs charge assignment
and force interpolation calculations on the GPU. These processes
are performed either in single or double precision, depending on
whether the -DFFT_SINGLE setting was specified in your low-level
Makefile, as discussed above. The FFTs themselves are still
calculated on the CPU. If *pppm/gpu* is used with a GPU-enabled
pair style, part of the PPPM calculation can be performed
concurrently on the GPU while other calculations for non-bonded and
bonded force calculation are performed on the CPU.
These accelerated styles are part of the GPU, INTEL, KOKKOS,
OPENMP, and OPT packages respectively. They are only enabled if
LAMMPS was built with those packages. See the :doc:`Build package <Build_package>` page for more info.
.. note::
See the :doc:`Speed packages <Speed_packages>` page for more
instructions on how to use the accelerated styles effectively.
For the KOKKOS package, the *pppm/kk* style performs charge
assignment and force interpolation calculations, along with the FFTs
themselves, on the GPU or (optionally) threaded on the CPU when
using OpenMP and FFTW3.
----------

4
doc/src/package.rst
View File

@ -27,7 +27,7 @@ Syntax
on = set Newton pairwise flag on (currently not allowed)
*pair/only* = *off* or *on*
off = apply "gpu" suffix to all available styles in the GPU package (default)
on - apply "gpu" suffix only pair styles
on = apply "gpu" suffix only pair styles
*binsize* value = size
size = bin size for neighbor list construction (distance units)
*split* = fraction
@ -166,7 +166,7 @@ intel", or "package omp" command with default settings.
set, either to default values or to specified settings. I.e. settings
from previous invocations do not persist across multiple invocations.
See the :doc:`Speed packages <Speed_packages>` page for more details
See the :doc:`Accelerator packages <Speed_packages>` page for more details
about using the various accelerator packages for speeding up LAMMPS
simulations.

16
doc/src/pair_agni.rst
View File

@ -67,21 +67,7 @@ and input files are provided in the examples/PACKAGES/agni directory.
----------
Styles with *omp* suffix is functionally the same as the corresponding
style without the suffix. They have been optimized to run faster,
depending on your available hardware, as discussed on the :doc:`Speed packages <Speed_packages>` doc page. The accelerated style takes
the same arguments and should produce the same results, except for
round-off and precision issues.
The accelerated style is part of the OPENMP. They are only enabled
if LAMMPS was built with those packages. See the :doc:`Build package <Build_package>` page for more info.
You can specify the accelerated style explicitly in your input script
by including their suffix, or you can use the :doc:`-suffix command-line switch <Run_options>` when you invoke LAMMPS, or you can use the
:doc:`suffix <suffix>` command in your input script.
See the :doc:`Speed packages <Speed_packages>` page for more
instructions on how to use the accelerated styles effectively.
.. include:: accel_styles.rst
----------

5
doc/src/pair_airebo.rst
View File

@ -229,6 +229,11 @@ but you would need to create your own AIREBO or AIREBO-M potential file
with coefficients listed in the appropriate units, if your simulation
does not use "metal" units.
The pair styles provided here **only** support potential files parameterized
for the elements carbon and hydrogen (designated with "C" and "H" in the
*pair_coeff* command. Using potential files for other elements will trigger
an error.
Related commands
""""""""""""""""

81
doc/src/pair_hybrid.rst
View File

@ -198,8 +198,8 @@ same:
Coefficients must be defined for each pair of atoms types via the
:doc:`pair_coeff <pair_coeff>` command as described above, or in the
data file read by the :doc:`read_data <read_data>` commands, or by
mixing as described below.
"Pair Coeffs" or "PairIJ Coeffs" section of the data file read by the
:doc:`read_data <read_data>` command, or by mixing as described below.
For all of the *hybrid*, *hybrid/overlay*, and *hybrid/scaled* styles,
every atom type pair I,J (where I <= J) must be assigned to at least one
@ -208,14 +208,21 @@ examples above, or in the data file read by the :doc:`read_data
<read_data>`, or by mixing as described below. Also all sub-styles
must be used at least once in a :doc:`pair_coeff <pair_coeff>` command.
.. note::
LAMMPS never performs mixing of parameters from different sub-styles,
**even** if they use the same type of coefficients, e.g. contain
a Lennard-Jones potential variant. Those parameters must be provided
explicitly.
If you want there to be no interactions between a particular pair of
atom types, you have 3 choices. You can assign the type pair to some
sub-style and use the :doc:`neigh_modify exclude type <neigh_modify>`
atom types, you have 3 choices. You can assign the pair of atom types
to some sub-style and use the :doc:`neigh_modify exclude type <neigh_modify>`
command. You can assign it to some sub-style and set the coefficients
so that there is effectively no interaction (e.g. epsilon = 0.0 in a LJ
potential). Or, for *hybrid*, *hybrid/overlay*, or *hybrid/scaled*
simulations, you can use this form of the pair_coeff command in your
input script:
input script or the "PairIJ Coeffs" section of your data file:
.. code-block:: LAMMPS
@ -238,19 +245,20 @@ styles with different requirements.
----------
Different force fields (e.g. CHARMM vs AMBER) may have different rules
for applying weightings that change the strength of pairwise
interactions between pairs of atoms that are also 1-2, 1-3, and 1-4
neighbors in the molecular bond topology, as normally set by the
:doc:`special_bonds <special_bonds>` command. Different weights can be
assigned to different pair hybrid sub-styles via the :doc:`pair_modify
special <pair_modify>` command. This allows multiple force fields to be
used in a model of a hybrid system, however, there is no consistent
approach to determine parameters automatically for the interactions
between the two force fields, this is only recommended when particles
Different force fields (e.g. CHARMM vs. AMBER) may have different rules
for applying exclusions or weights that change the strength of pairwise
non-bonded interactions between pairs of atoms that are also 1-2, 1-3,
and 1-4 neighbors in the molecular bond topology. This is normally a
global setting defined the :doc:`special_bonds <special_bonds>` command.
However, different weights can be assigned to different hybrid
sub-styles via the :doc:`pair_modify special <pair_modify>` command.
This allows multiple force fields to be used in a model of a hybrid
system, however, there is no consistent approach to determine parameters
automatically for the interactions **between** atoms of the two force
fields, thus this approach this is only recommended when particles
described by the different force fields do not mix.
Here is an example for mixing CHARMM and AMBER: The global *amber*
Here is an example for combining CHARMM and AMBER: The global *amber*
setting sets the 1-4 interactions to non-zero scaling factors and
then overrides them with 0.0 only for CHARMM:
@ -260,7 +268,7 @@ then overrides them with 0.0 only for CHARMM:
pair_style hybrid lj/charmm/coul/long 8.0 10.0 lj/cut/coul/long 10.0
pair_modify pair lj/charmm/coul/long special lj/coul 0.0 0.0 0.0
The this input achieves the same effect:
This input achieves the same effect:
.. code-block:: LAMMPS
@ -270,9 +278,9 @@ The this input achieves the same effect:
pair_modify pair lj/cut/coul/long special coul 0.0 0.0 0.83333333
pair_modify pair lj/charmm/coul/long special lj/coul 0.0 0.0 0.0
Here is an example for mixing Tersoff with OPLS/AA based on
a data file that defines bonds for all atoms where for the
Tersoff part of the system the force constants for the bonded
Here is an example for combining Tersoff with OPLS/AA based on
a data file that defines bonds for all atoms where - for the
Tersoff part of the system - the force constants for the bonded
interactions have been set to 0. Note the global settings are
effectively *lj/coul 0.0 0.0 0.5* as required for OPLS/AA:
@ -375,30 +383,19 @@ coefficients to 0.0.
----------
Styles with a *gpu*, *intel*, *kk*, *omp*, or *opt* suffix are
functionally the same as the corresponding style without the suffix.
They have been optimized to run faster, depending on your available
hardware, as discussed on the :doc:`Speed packages <Speed_packages>` doc
page. Pair style *hybrid/scaled* does (currently) not support the
*gpu*, *omp*, *kk*, or *intel* suffix.
.. include:: accel_styles.rst
Since the *hybrid*, *hybrid/overlay*, *hybrid/scaled* styles delegate
computation to the individual sub-styles, the suffix versions of the
*hybrid* and *hybrid/overlay* styles are used to propagate the
corresponding suffix to all sub-styles, if those versions
exist. Otherwise the non-accelerated version will be used.
.. note::
The individual accelerated sub-styles are part of the GPU, KOKKOS,
INTEL, OPENMP, and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the :doc:`Build
package <Build_package>` page for more info.
You can specify the accelerated styles explicitly in your input script
by including their suffix, or you can use the :doc:`-suffix command-line switch <Run_options>` when you invoke LAMMPS, or you can use the
:doc:`suffix <suffix>` command in your input script.
See the :doc:`Speed packages <Speed_packages>` page for more
instructions on how to use the accelerated styles effectively.
Since the *hybrid*, *hybrid/overlay*, *hybrid/scaled* styles
delegate computation to the individual sub-styles, the suffix
versions of the *hybrid* and *hybrid/overlay* styles are used to
propagate the corresponding suffix to all sub-styles, if those
versions exist. Otherwise the non-accelerated version will be used.
The individual accelerated sub-styles are part of the GPU, KOKKOS,
INTEL, OPENMP, and OPT packages, respectively. They are only
enabled if LAMMPS was built with those packages. See the
:doc:`Build package <Build_package>` page for more info.
----------

6
doc/src/pair_oxdna.rst
View File

@ -104,10 +104,10 @@ A simple python setup tool which creates single straight or helical DNA strands,
DNA duplexes or arrays of DNA duplexes can be found in examples/PACKAGES/cgdna/util/.
Please cite :ref:`(Henrich) <Henrich1>` in any publication that uses
this implementation. The article contains general information
this implementation. An updated documentation that contains general information
on the model, its implementation and performance as well as the structure of
the data and input file. The preprint version of the article can be found
`here <PDF/CG-DNA.pdf>`_.
the data and input file can be found `here <PDF/CG-DNA.pdf>`_.
Please cite also the relevant oxDNA publications
:ref:`(Ouldridge) <Ouldridge1>`,
:ref:`(Ouldridge-DPhil) <Ouldridge-DPhil1>`

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