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

Merge branch 'develop' into pimd_langevin

Browse Source
This commit is contained in:
Axel Kohlmeyer
2023-05-17 17:30:49 -04:00
parent 42758d0780 a84470383b
commit 39f61b6af3
866 changed files with 58391 additions and 67475 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
doc/src/Build_basics.rst
View File

@ -128,14 +128,14 @@ and adds vectorization support when compiled with compatible compilers,
in particular the Intel compilers on top of OpenMP. Also, the ``KOKKOS``
package can be compiled to include OpenMP threading.
In addition, there are a few commands in LAMMPS that have native OpenMP
support included as well. These are commands in the ``MPIIO``,
``ML-SNAP``, ``DIFFRACTION``, and ``DPD-REACT`` packages. Furthermore,
some packages support OpenMP threading indirectly through the libraries
they interface to: e.g. ``LATTE``, ``KSPACE``, and ``COLVARS``. See the
:doc:`Packages details <Packages_details>` page for more info on these
packages, and the pages for their respective commands for OpenMP
threading info.
In addition, there are a few commands in LAMMPS that have native
OpenMP support included as well. These are commands in the ``MPIIO``,
``ML-SNAP``, ``DIFFRACTION``, and ``DPD-REACT`` packages.
Furthermore, some packages support OpenMP threading indirectly through
the libraries they interface to: e.g. ``KSPACE``, and ``COLVARS``.
See the :doc:`Packages details <Packages_details>` page for more info
on these packages, and the pages for their respective commands for
OpenMP threading info.
For CMake, if you use ``BUILD_OMP=yes``, you can use these packages
and turn on their native OpenMP support and turn on their native OpenMP

2
doc/src/Build_development.rst
View File

@ -523,6 +523,8 @@ The following options are available.
These should help to make source and documentation files conforming
to some the coding style preferences of the LAMMPS developers.
.. _clang-format:
Clang-format support
--------------------

75
doc/src/Build_extras.rst
View File

@ -43,7 +43,6 @@ This is the list of packages that may require additional steps.
* :ref:`INTEL <intel>`
* :ref:`KIM <kim>`
* :ref:`KOKKOS <kokkos>`
* :ref:`LATTE <latte>`
* :ref:`LEPTON <lepton>`
* :ref:`MACHDYN <machdyn>`
* :ref:`MDI <mdi>`
@ -684,20 +683,11 @@ This list was last updated for version 3.7.1 of the Kokkos library.
-D Kokkos_ARCH_GPUARCH=yes # GPUARCH = GPU from list above
-D Kokkos_ENABLE_CUDA=yes
-D Kokkos_ENABLE_OPENMP=yes
-D CMAKE_CXX_COMPILER=wrapper # wrapper = full path to Cuda nvcc wrapper
This will also enable executing FFTs on the GPU, either via the
internal KISSFFT library, or - by preference - with the cuFFT
library bundled with the CUDA toolkit, depending on whether CMake
can identify its location. The *wrapper* value for
``CMAKE_CXX_COMPILER`` variable is the path to the CUDA nvcc
compiler wrapper provided in the Kokkos library:
``lib/kokkos/bin/nvcc_wrapper``\ . The setting should include the
full path name to the wrapper, e.g.
.. code-block:: bash
-D CMAKE_CXX_COMPILER=${HOME}/lammps/lib/kokkos/bin/nvcc_wrapper
can identify its location.
For AMD or NVIDIA GPUs using HIP, set these variables:
@ -832,63 +822,6 @@ will thus always enable it.
----------
.. _latte:
LATTE package
-------------------------
To build with this package, you must download and build the LATTE
library.
.. tabs::
.. tab:: CMake build
.. code-block:: bash
-D DOWNLOAD_LATTE=value # download LATTE for build, value = no (default) or yes
-D LATTE_LIBRARY=path # LATTE library file (only needed if a custom location)
-D USE_INTERNAL_LINALG=value # Use the internal linear algebra library instead of LAPACK
# value = no (default) or yes
If ``DOWNLOAD_LATTE`` is set, the LATTE library will be downloaded
and built inside the CMake build directory. If the LATTE library
is already on your system (in a location CMake cannot find it),
``LATTE_LIBRARY`` is the filename (plus path) of the LATTE library
file, not the directory the library file is in.
The LATTE library requires LAPACK (and BLAS) and CMake can identify
their locations and pass that info to the LATTE build script. But
on some systems this triggers a (current) limitation of CMake and
the configuration will fail. Try enabling ``USE_INTERNAL_LINALG`` in
those cases to use the bundled linear algebra library and work around
the limitation.
.. tab:: Traditional make
You can download and build the LATTE library manually if you
prefer; follow the instructions in ``lib/latte/README``\ . You
can also do it in one step from the ``lammps/src`` dir, using a
command like these, which simply invokes the
``lib/latte/Install.py`` script with the specified args:
.. code-block:: bash
make lib-latte # print help message
make lib-latte args="-b" # download and build in lib/latte/LATTE-master
make lib-latte args="-p $HOME/latte" # use existing LATTE installation in $HOME/latte
make lib-latte args="-b -m gfortran" # download and build in lib/latte and
# copy Makefile.lammps.gfortran to Makefile.lammps
Note that 3 symbolic (soft) links, ``includelink`` and ``liblink``
and ``filelink.o``, are created in ``lib/latte`` to point to
required folders and files in the LATTE home directory. When
LAMMPS itself is built it will use these links. You should also
check that the ``Makefile.lammps`` file you create is appropriate
for the compiler you use on your system to build LATTE.
----------
.. _lepton:
LEPTON package
@ -1413,9 +1346,9 @@ This package depends on the KSPACE package.
KSPACE package so the latter one *must* be enabled.
The ELECTRODE package also requires LAPACK (and BLAS) and CMake
can identify their locations and pass that info to the LATTE build
script. But on some systems this may cause problems when linking
or the dependency is not desired. Try enabling
can identify their locations and pass that info to the ELECTRODE
build script. But on some systems this may cause problems when
linking or the dependency is not desired. Try enabling
``USE_INTERNAL_LINALG`` in those cases to use the bundled linear
algebra library and work around the limitation.

4
doc/src/Build_make.rst
View File

@ -117,8 +117,8 @@ their settings may become outdated, too:
.. code-block:: bash
make mac # build serial LAMMPS on a Mac
make mac_mpi # build parallel LAMMPS on a Mac
make mac # build serial LAMMPS on macOS
make mac_mpi # build parallel LAMMPS on macOS
make intel_cpu # build with the INTEL package optimized for CPUs
make knl # build with the INTEL package optimized for KNLs
make opt # build with the OPT package optimized for CPUs

10
doc/src/Build_manual.rst
View File

@ -52,11 +52,11 @@ can be translated to different output format using the `Sphinx
incorporates programmer documentation extracted from the LAMMPS C++
sources through the `Doxygen <https://doxygen.nl/>`_ program. Currently
the translation to HTML, PDF (via LaTeX), ePUB (for many e-book readers)
and MOBI (for Amazon Kindle readers) are supported. For that to work a
Python 3 interpreter, the ``doxygen`` tools and internet access to
download additional files and tools are required. This download is
usually only required once or after the documentation folder is returned
to a pristine state with ``make clean-all``.
and MOBI (for Amazon Kindle(tm) readers) are supported. For that to work a
Python interpreter version 3.8 or later, the ``doxygen`` tools and
internet access to download additional files and tools are required.
This download is usually only required once or after the documentation
folder is returned to a pristine state with ``make clean-all``.
For the documentation build a python virtual environment is set up in
the folder ``doc/docenv`` and various python packages are installed into

1
doc/src/Build_package.rst
View File

@ -46,7 +46,6 @@ packages:
* :ref:`INTEL <intel>`
* :ref:`KIM <kim>`
* :ref:`KOKKOS <kokkos>`
* :ref:`LATTE <latte>`
* :ref:`LEPTON <lepton>`
* :ref:`MACHDYN <machdyn>`
* :ref:`MDI <mdi>`

3
doc/src/Commands_compute.rst
View File

@ -46,6 +46,7 @@ KOKKOS, o = OPENMP, t = OPT.
* :doc:`com/chunk <compute_com_chunk>`
* :doc:`contact/atom <compute_contact_atom>`
* :doc:`coord/atom (k) <compute_coord_atom>`
* :doc:`count/type <compute_count_type>`
* :doc:`damage/atom <compute_damage_atom>`
* :doc:`dihedral <compute_dihedral>`
* :doc:`dihedral/local <compute_dihedral_local>`
@ -63,7 +64,7 @@ KOKKOS, o = OPENMP, t = OPT.
* :doc:`entropy/atom <compute_entropy_atom>`
* :doc:`erotate/asphere <compute_erotate_asphere>`
* :doc:`erotate/rigid <compute_erotate_rigid>`
* :doc:`erotate/sphere <compute_erotate_sphere>`
* :doc:`erotate/sphere (k) <compute_erotate_sphere>`
* :doc:`erotate/sphere/atom <compute_erotate_sphere_atom>`
* :doc:`event/displace <compute_event_displace>`
* :doc:`fabric <compute_fabric>`

4
doc/src/Commands_fix.rst
View File

@ -104,13 +104,13 @@ OPT.
* :doc:`langevin/drude <fix_langevin_drude>`
* :doc:`langevin/eff <fix_langevin_eff>`
* :doc:`langevin/spin <fix_langevin_spin>`
* :doc:`latte <fix_latte>`
* :doc:`lb/fluid <fix_lb_fluid>`
* :doc:`lb/momentum <fix_lb_momentum>`
* :doc:`lb/viscous <fix_lb_viscous>`
* :doc:`lineforce <fix_lineforce>`
* :doc:`manifoldforce <fix_manifoldforce>`
* :doc:`mdi/qm <fix_mdi_qm>`
* :doc:`mdi/qmmm <fix_mdi_qmmm>`
* :doc:`meso/move <fix_meso_move>`
* :doc:`mol/swap <fix_mol_swap>`
* :doc:`momentum (k) <fix_momentum>`
@ -261,7 +261,7 @@ OPT.
* :doc:`wall/body/polyhedron <fix_wall_body_polyhedron>`
* :doc:`wall/colloid <fix_wall>`
* :doc:`wall/ees <fix_wall_ees>`
* :doc:`wall/gran <fix_wall_gran>`
* :doc:`wall/gran (k) <fix_wall_gran>`
* :doc:`wall/gran/region <fix_wall_gran_region>`
* :doc:`wall/harmonic <fix_wall>`
* :doc:`wall/lj1043 <fix_wall>`

4
doc/src/Commands_pair.rst
View File

@ -55,6 +55,7 @@ OPT.
* :doc:`born/coul/msm (o) <pair_born>`
* :doc:`born/coul/wolf (go) <pair_born>`
* :doc:`born/coul/wolf/cs (g) <pair_cs>`
* :doc:`born/gauss <pair_born_gauss>`
* :doc:`bpm/spring <pair_bpm_spring>`
* :doc:`brownian (o) <pair_brownian>`
* :doc:`brownian/poly (o) <pair_brownian>`
@ -136,6 +137,7 @@ OPT.
* :doc:`lennard/mdf <pair_mdf>`
* :doc:`lepton (o) <pair_lepton>`
* :doc:`lepton/coul (o) <pair_lepton>`
* :doc:`lepton/sphere (o) <pair_lepton>`
* :doc:`line/lj <pair_line_lj>`
* :doc:`lj/charmm/coul/charmm (giko) <pair_charmm>`
* :doc:`lj/charmm/coul/charmm/implicit (ko) <pair_charmm>`
@ -170,12 +172,14 @@ OPT.
* :doc:`lj/cut/dipole/long (g) <pair_dipole>`
* :doc:`lj/cut/dipole/sf (go) <pair_dipole>`
* :doc:`lj/cut/soft (o) <pair_fep_soft>`
* :doc:`lj/cut/sphere (o) <pair_lj_cut_sphere>`
* :doc:`lj/cut/thole/long (o) <pair_thole>`
* :doc:`lj/cut/tip4p/cut (o) <pair_lj_cut_tip4p>`
* :doc:`lj/cut/tip4p/long (got) <pair_lj_cut_tip4p>`
* :doc:`lj/cut/tip4p/long/soft (o) <pair_fep_soft>`
* :doc:`lj/expand (gko) <pair_lj_expand>`
* :doc:`lj/expand/coul/long (gk) <pair_lj_expand>`
* :doc:`lj/expand/sphere (o) <pair_lj_expand_sphere>`
* :doc:`lj/gromacs (gko) <pair_gromacs>`
* :doc:`lj/gromacs/coul/gromacs (ko) <pair_gromacs>`
* :doc:`lj/long/coul/long (iot) <pair_lj_long>`

14
doc/src/Commands_removed.rst
View File

@ -38,6 +38,20 @@ been folded into the :doc:`reset_atoms <reset_atoms>` command. If
present, LAMMPS will replace the commands accordingly and print a
warning.
LATTE package
-------------
.. deprecated:: TBD
The LATTE package with the fix latte command was removed from LAMMPS.
This functionality has been superseded by :doc:`fix mdi/qm <fix_mdi_qm>`
and :doc:`fix mdi/qmmm <fix_mdi_qmmm>` from the :ref:`MDI package
<PKG-MDI>`. These fixes are compatible with several quantum software
packages, including LATTE. See the ``examples/QUANTUM`` dir and the
:doc:`MDI coupling HOWTO <Howto_mdi>` page. MDI supports running LAMMPS
with LATTE as a plugin library (similar to the way fix latte worked), as
well as on a different set of MPI processors.
MEAM package
------------

1
doc/src/Developer.rst
View File

@ -13,6 +13,7 @@ of time and requests from the LAMMPS user community.
Developer_org
Developer_code_design
Developer_parallel
Developer_atom
Developer_comm_ops
Developer_flow
Developer_write

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

@ -0,0 +1,88 @@
Accessing per-atom data
-----------------------
This page discusses how per-atom data is managed in LAMMPS, how it can
be accessed, what communication patters apply, and some of the utility
functions that exist for a variety of purposes.
Owned and ghost atoms
^^^^^^^^^^^^^^^^^^^^^
As described on the :doc:`parallel partitioning algorithms
<Developer_par_part>` page, LAMMPS uses a domain decomposition of the
simulation domain, either in a *brick* or *tiled* manner. Each MPI
process *owns* exactly one subdomain and the atoms within it. To compute
forces for tuples of atoms that are spread across sub-domain boundaries,
also a "halo" of *ghost* atoms are maintained within a the communication
cutoff distance of its subdomain.
The total number of atoms is stored in `Atom::natoms` (within any
typical class this can be referred to at `atom->natoms`. The number of
*owned* (or "local" atoms) are stored in `Atom::nlocal`; the number of
*ghost* atoms is stored in `Atom::nghost`. The sum of `Atom::nlocal`
over all MPI processes should be `Atom::natoms`. This is by default
regularly checked by the Thermo class, and if the sum does not match,
LAMMPS stops with a "lost atoms" error. For convenience also the
property `Atom::nmax` is available, this is the maximum of
`Atom::nlocal + Atom::nghost` across all MPI processes.
Per-atom properties are either managed by the atom style, or individual
classes. or as custom arrays by the individual classes. If only access
to *owned* atoms is needed, they are usually allocated to be of size
`Atom::nlocal`, otherwise of size `Atom::nmax`. Please note that not all
per-atom properties are available or updated on *ghost* atoms. For
example, per-atom velocities are only updated with :doc:`comm_modify vel
yes <comm_modify>`.
Atom indexing
^^^^^^^^^^^^^
When referring to individual atoms, they may be indexed by their local
*index*, their index in their `Atom::x` array. This is densely populated
containing first all *owned* atoms (index < `Atom::nlocal`) and then all
*ghost* atoms. The order of atoms in these arrays can change due to
atoms migrating between between subdomains, atoms being added or
deleted, or atoms being sorted for better cache efficiency. Atoms are
globally uniquely identified by their *atom ID*. There may be multiple
atoms with the same atom ID present, but only one of them may be an
*owned* atom.
To find the local *index* of an atom, when the *atom ID* is known, the
`Atom::map()` function may be used. It will return the local atom index
or -1. If the returned value is between 0 (inclusive) and `Atom::nlocal`
(exclusive) it is an *owned* or "local" atom; for larger values the atom
is present as a ghost atom; for a value of -1, the atom is not present
on the current subdomain at all.
If multiple atoms with the same tag exist in the same subdomain, they
can be found via the `Atom::sametag` array. It points to the next atom
index with the same tag or -1 if there are no more atoms with the same
tag. The list will be exhaustive when starting with an index of an
*owned* atom, since the atom IDs are unique, so there can only be one
such atom. Example code to count atoms with same atom ID in subdomain:
.. code-block:: c++
for (int i = 0; i < atom->nlocal; ++i) {
int count = 0;
while (sametag[i] >= 0) {
i = sametag[i];
++count;
}
printf("Atom ID: %ld is present %d times\n", atom->tag[i], count);
}
Atom class versus AtomVec classes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The `Atom` class contains all kinds of flags and counters about atoms in
the system and that includes pointers to **all** per-atom properties
available for atoms. However, only a subset of these pointers are
non-NULL and which those are depends on the atom style. For each atom
style there is a corresponding `AtomVecXXX` class derived from the
`AtomVec` base class, where the XXX indicates the atom style. This
`AtomVecXXX` class will update the counters and per-atom pointers if
atoms are added or removed to the system or migrate between subdomains.

2
doc/src/Developer_notes.rst
View File

@ -74,6 +74,8 @@ when converting "12.5", while the ValueTokenizer class will throw an
:cpp:func:`ValueTokenizer::next_int()
<LAMMPS_NS::ValueTokenizer::next_int>` is called on the same string.
.. _request-neighbor-list:
Requesting and accessing neighbor lists
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

2
doc/src/Developer_updating.rst
View File

@ -389,7 +389,7 @@ This change is **required** or else the code will not compile.
Rename of fix STORE/PERATOM to fix STORE/ATOM and change of arguments
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionchanged:: TBD
.. versionchanged:: 28Mar2023
The available functionality of the internal fix to store per-atom
properties was expanded to enable storing data with ghost atoms and to

249
doc/src/Developer_write.rst
View File

@ -6,250 +6,9 @@ be extended by writing new classes that derive from existing
parent classes in LAMMPS. Here, some specific coding
details are provided for writing code for LAMMPS.
Writing a new fix style
^^^^^^^^^^^^^^^^^^^^^^^
Writing fixes is a flexible way of extending LAMMPS. Users can
implement many things using fixes:
- changing particles attributes (positions, velocities, forces, etc.). Examples: FixNVE, FixFreeze.
- reading/writing data. Example: FixRestart.
- adding or modifying properties due to geometry. Example: FixWall.
- interacting with other subsystems or external code: Examples: FixTTM, FixExternal, FixLATTE
- saving information for analysis or future use (previous positions,
for instance). Examples: Fix AveTime, FixStoreState.
All fixes are derived from the Fix base class and must have a
constructor with the signature: ``FixPrintVel(class LAMMPS *, int, char **)``.
Every fix must be registered in LAMMPS by writing the following lines
of code in the header before include guards:
.. code-block:: c++
#ifdef FIX_CLASS
// clang-format off
FixStyle(print/vel,FixPrintVel);
// clang-format on
#else
/* the definition of the FixPrintVel class comes here */
...
#endif
Where ``print/vel`` is the style name of your fix in the input script and
``FixPrintVel`` is the name of the class. The header file would be called
``fix_print_vel.h`` and the implementation file ``fix_print_vel.cpp``.
These conventions allow LAMMPS to automatically integrate it into the
executable when compiling and associate your new fix class with the designated
keyword when it parses the input script.
Let's write a simple fix which will print the average velocity at the end
of each timestep. First of all, implement a constructor:
.. code-block:: c++
FixPrintVel::FixPrintVel(LAMMPS *lmp, int narg, char **arg)
: Fix(lmp, narg, arg)
{
if (narg < 4)
error->all(FLERR,"Illegal fix print/vel command");
nevery = utils::inumeric(FLERR,arg[3],false,lmp);
if (nevery <= 0)
error->all(FLERR,"Illegal fix print/vel command");
}
In the constructor you should parse your fix arguments which are
specified in the script. All fixes have pretty much the same syntax:
``fix <fix-ID> <fix group> <fix name> <fix arguments ...>``. The
first 3 parameters are parsed by Fix base class constructor, while
``<fix arguments>`` should be parsed by you. In our case, we need to
specify how often we want to print an average velocity. For instance,
once in 50 timesteps: ``fix 1 print/vel 50``. There is a special variable
in the Fix class called ``nevery`` which specifies how often the method
``end_of_step()`` is called. Thus all we need to do is just set it up.
The next method we need to implement is ``setmask()``:
.. code-block:: c++
int FixPrintVel::setmask()
{
int mask = 0;
mask |= FixConst::END_OF_STEP;
return mask;
}
Here the user specifies which methods of your fix should be called
during execution. The constant ``END_OF_STEP`` corresponds to the
``end_of_step()`` method. The most important available methods that
are called during a timestep and the order in which they are called
are shown in the previous section.
.. code-block:: c++
void FixPrintVel::end_of_step()
{
// for add3, scale3
using namespace MathExtra;
double** v = atom->v;
int nlocal = atom->nlocal;
double localAvgVel[4]; // 4th element for particles count
memset(localAvgVel, 0, 4 * sizeof(double));
for (int particleInd = 0; particleInd < nlocal; ++particleInd) {
add3(localAvgVel, v[particleInd], localAvgVel);
}
localAvgVel[3] = nlocal;
double globalAvgVel[4];
memset(globalAvgVel, 0, 4 * sizeof(double));
MPI_Allreduce(localAvgVel, globalAvgVel, 4, MPI_DOUBLE, MPI_SUM, world);
scale3(1.0 / globalAvgVel[3], globalAvgVel);
if ((comm->me == 0) && screen) {
fmt::print(screen,"{}, {}, {}\n",
globalAvgVel[0], globalAvgVel[1], globalAvgVel[2]);
}
}
In the code above, we use MathExtra routines defined in
``math_extra.h``. There are bunch of math functions to work with
arrays of doubles as with math vectors. It is also important to note
that LAMMPS code should always assume to be run in parallel and that
atom data is thus distributed across the MPI ranks. Thus you can
only process data from local atoms directly and need to use MPI library
calls to combine or exchange data. For serial execution, LAMMPS
comes bundled with the MPI STUBS library that contains the MPI library
function calls in dummy versions that only work for a single MPI rank.
In this code we use an instance of Atom class. This object is stored
in the Pointers class (see ``pointers.h``) which is the base class of
the Fix base class. This object contains references to various class
instances (the original instances are created and held by the LAMMPS
class) with all global information about the simulation system.
Data from the Pointers class is available to all classes inherited from
it using protected inheritance. Hence when you write you own class,
which is going to use LAMMPS data, don't forget to inherit from Pointers
or pass an Pointer to it to all functions that need access. When writing
fixes we inherit from class Fix which is inherited from Pointers so
there is no need to inherit from it directly.
The code above computes average velocity for all particles in the
simulation. Yet you have one unused parameter in fix call from the
script: ``group_name``. This parameter specifies the group of atoms
used in the fix. So we should compute average for all particles in the
simulation only if ``group_name == "all"``, but it can be any group.
The group membership information of an atom is contained in the *mask*
property of and atom and the bit corresponding to a given group is
stored in the groupbit variable which is defined in Fix base class:
.. code-block:: c++
for (int i = 0; i < nlocal; ++i) {
if (atom->mask[i] & groupbit) {
// Do all job here
}
}
Class Atom encapsulates atoms positions, velocities, forces, etc. User
can access them using particle index. Note, that particle indexes are
usually changed every few timesteps because of neighbor list rebuilds
and spatial sorting (to improve cache efficiency).
Let us consider another Fix example: We want to have a fix which stores
atoms position from previous time step in your fix. The local atoms
indexes may not be valid on the next iteration. In order to handle
this situation there are several methods which should be implemented:
- ``double memory_usage()``: return how much memory the fix uses (optional)
- ``void grow_arrays(int)``: do reallocation of the per particle arrays in your fix
- ``void copy_arrays(int i, int j, int delflag)``: copy i-th per-particle
information to j-th. Used when atom sorting is performed. if delflag is set
and atom j owns a body, move the body information to atom i.
- ``void set_arrays(int i)``: sets i-th particle related information to zero
Note, that if your class implements these methods, it must call add calls of
add_callback and delete_callback to constructor and destructor. Since we want
to store positions of atoms from previous timestep, we need to add
``double** xold`` to the header file. Than add allocation code
to the constructor:
.. code-block:: c++
FixSavePos::FixSavePos(LAMMPS *lmp, int narg, char **arg), xold(nullptr)
{
//...
memory->create(xold, atom->nmax, 3, "FixSavePos:x");
atom->add_callback(0);
}
FixSavePos::~FixSavePos() {
atom->delete_callback(id, 0);
memory->destroy(xold);
}
Implement the aforementioned methods:
.. code-block:: c++
double FixSavePos::memory_usage()
{
int nmax = atom->nmax;
double bytes = 0.0;
bytes += nmax * 3 * sizeof(double);
return bytes;
}
void FixSavePos::grow_arrays(int nmax)
{
memory->grow(xold, nmax, 3, "FixSavePos:xold");
}
void FixSavePos::copy_arrays(int i, int j, int delflag)
{
memcpy(xold[j], xold[i], sizeof(double) * 3);
}
void FixSavePos::set_arrays(int i)
{
memset(xold[i], 0, sizeof(double) * 3);
}
int FixSavePos::pack_exchange(int i, double *buf)
{
int m = 0;
buf[m++] = xold[i][0];
buf[m++] = xold[i][1];
buf[m++] = xold[i][2];
return m;
}
int FixSavePos::unpack_exchange(int nlocal, double *buf)
{
int m = 0;
xold[nlocal][0] = buf[m++];
xold[nlocal][1] = buf[m++];
xold[nlocal][2] = buf[m++];
return m;
}
Now, a little bit about memory allocation. We use the Memory class which
is just a bunch of template functions for allocating 1D and 2D
arrays. So you need to add include ``memory.h`` to have access to them.
Finally, if you need to write/read some global information used in
your fix to the restart file, you might do it by setting flag
``restart_global = 1`` in the constructor and implementing methods void
``write_restart(FILE *fp)`` and ``void restart(char *buf)``.
If, in addition, you want to write the per-atom property to restart
files additional settings and functions are needed:
- a fix flag indicating this needs to be set ``restart_peratom = 1;``
- ``atom->add_callback()`` and ``atom->delete_callback()`` must be called
a second time with the final argument set to 1 instead of 0 (indicating
restart processing instead of per-atom data memory management).
- the functions ``void pack_restart(int i, double *buf)`` and
``void unpack_restart(int nlocal, int nth)`` need to be implemented
.. toctree::
:maxdepth: 1
Developer_write_pair
Developer_write_fix

245
doc/src/Developer_write_fix.rst Normal file
View File

@ -0,0 +1,245 @@
Writing a new fix style
^^^^^^^^^^^^^^^^^^^^^^^
Writing fix styles is a flexible way of extending LAMMPS. Users can
implement many things using fixes. Some fix styles are only used
internally to support compute styles or pair styles:
- change particles attributes (positions, velocities, forces, etc.). Examples: ``FixNVE``, ``FixFreeze``.
- read or write data. Example: ``FixRestart``.
- adding or modifying properties due to geometry. Example: ``FixWall``.
- interacting with other subsystems or external code: Examples: ``FixTTM``, ``FixExternal``, ``FixMDI``
- saving information for analysis or future use (previous positions,
for instance). Examples: ``FixAveTime``, ``FixStoreState``.
All fixes are derived from the ``Fix`` base class and must have a
constructor with the signature: ``FixPrintVel(class LAMMPS *, int, char **)``.
Every fix must be registered in LAMMPS by writing the following lines
of code in the header before include guards:
.. code-block:: c++
#ifdef FIX_CLASS
// clang-format off
FixStyle(print/vel,FixPrintVel);
// clang-format on
#else
/* the definition of the FixPrintVel class comes here */
...
#endif
Where ``print/vel`` is the style name of your fix in the input script and
``FixPrintVel`` is the name of the class. The header file would be called
``fix_print_vel.h`` and the implementation file ``fix_print_vel.cpp``.
These conventions allow LAMMPS to automatically integrate it into the
executable when compiling and associate your new fix class with the designated
keyword when it parses the input script.
Let's write a simple fix which will print the average velocity at the end
of each timestep. First of all, implement a constructor:
.. code-block:: c++
FixPrintVel::FixPrintVel(LAMMPS *lmp, int narg, char **arg)
: Fix(lmp, narg, arg)
{
if (narg < 4) utils::missing_cmd_args(FLERR, "fix print/vel", error);
nevery = utils::inumeric(FLERR,arg[3],false,lmp);
if (nevery <= 0)
error->all(FLERR,"Illegal fix print/vel nevery value: {}", nevery);
}
In the constructor you should parse the fix arguments which are
specified in the script. All fixes have pretty much the same syntax:
``fix <fix-ID> <fix group> <fix name> <fix arguments ...>``. The first 3
parameters are parsed by Fix base class constructor, while ``<fix
arguments>`` should be parsed by you. In our case, we need to specify
how often we want to print an average velocity. For instance, once in 50
timesteps: ``fix 1 print/vel 50``. There is a special variable in the
Fix class called ``nevery`` which specifies how often the method
``end_of_step()`` is called. Thus all we need to do is just set it up.
The next method we need to implement is ``setmask()``:
.. code-block:: c++
int FixPrintVel::setmask()
{
int mask = 0;
mask |= FixConst::END_OF_STEP;
return mask;
}
Here the we specify which methods of the fix should be called during
:doc:`execution of a timestep <Developer_flow>`. The constant
``END_OF_STEP`` corresponds to the ``end_of_step()`` method. The most
important available methods that are called during a timestep.
.. code-block:: c++
void FixPrintVel::end_of_step()
{
// for add3, scale3
using namespace MathExtra;
double** v = atom->v;
int nlocal = atom->nlocal;
double localAvgVel[4]; // 4th element for particles count
memset(localAvgVel, 0, 4 * sizeof(double));
for (int particleInd = 0; particleInd < nlocal; ++particleInd) {
add3(localAvgVel, v[particleInd], localAvgVel);
}
localAvgVel[3] = nlocal;
double globalAvgVel[4];
memset(globalAvgVel, 0, 4 * sizeof(double));
MPI_Allreduce(localAvgVel, globalAvgVel, 4, MPI_DOUBLE, MPI_SUM, world);
scale3(1.0 / globalAvgVel[3], globalAvgVel);
if ((comm->me == 0) && screen) {
fmt::print(screen,"{}, {}, {}\n",
globalAvgVel[0], globalAvgVel[1], globalAvgVel[2]);
}
}
In the code above, we use MathExtra routines defined in
``math_extra.h``. There are bunch of math functions to work with
arrays of doubles as with math vectors. It is also important to note
that LAMMPS code should always assume to be run in parallel and that
atom data is thus distributed across the MPI ranks. Thus you can
only process data from local atoms directly and need to use MPI library
calls to combine or exchange data. For serial execution, LAMMPS
comes bundled with the MPI STUBS library that contains the MPI library
function calls in dummy versions that only work for a single MPI rank.
In this code we use an instance of Atom class. This object is stored
in the Pointers class (see ``pointers.h``) which is the base class of
the Fix base class. This object contains references to various class
instances (the original instances are created and held by the LAMMPS
class) with all global information about the simulation system.
Data from the Pointers class is available to all classes inherited from
it using protected inheritance. Hence when you write you own class,
which is going to use LAMMPS data, don't forget to inherit from Pointers
or pass a Pointer to it to all functions that need access. When writing
fixes we inherit from class Fix which is inherited from Pointers so
there is no need to inherit from it directly.
The code above computes average velocity for all particles in the
simulation. Yet you have one unused parameter in fix call from the
script: ``group_name``. This parameter specifies the group of atoms
used in the fix. So we should compute average for all particles in the
simulation only if ``group_name == "all"``, but it can be any group.
The group membership information of an atom is contained in the *mask*
property of an atom and the bit corresponding to a given group is
stored in the groupbit variable which is defined in Fix base class:
.. code-block:: c++
for (int i = 0; i < nlocal; ++i) {
if (atom->mask[i] & groupbit) {
// Do all job here
}
}
Class Atom encapsulates atoms positions, velocities, forces, etc. Users
can access them using particle index. Note, that particle indexes are
usually changed every few timesteps because of neighbor list rebuilds
and spatial sorting (to improve cache efficiency).
Let us consider another Fix example: We want to have a fix which stores
atoms position from the previous time step in your fix. The local atoms
indexes may not be valid on the next iteration. In order to handle
this situation there are several methods which should be implemented:
- ``double memory_usage()``: return how much memory the fix uses (optional)
- ``void grow_arrays(int)``: do reallocation of the per-particle arrays in your fix
- ``void copy_arrays(int i, int j, int delflag)``: copy i-th per-particle
information to j-th. Used when atom sorting is performed. if delflag is set
and atom j owns a body, move the body information to atom i.
- ``void set_arrays(int i)``: sets i-th particle related information to zero
Note, that if your class implements these methods, it must add calls of
add_callback and delete_callback to the constructor and destructor. Since we want
to store positions of atoms from the previous timestep, we need to add
``double** xold`` to the header file. Than add allocation code
to the constructor:
.. code-block:: c++
FixSavePos::FixSavePos(LAMMPS *lmp, int narg, char **arg), xold(nullptr)
{
//...
memory->create(xold, atom->nmax, 3, "FixSavePos:x");
atom->add_callback(0);
}
FixSavePos::~FixSavePos() {
atom->delete_callback(id, 0);
memory->destroy(xold);
}
Implement the aforementioned methods:
.. code-block:: c++
double FixSavePos::memory_usage()
{
int nmax = atom->nmax;
double bytes = 0.0;
bytes += nmax * 3 * sizeof(double);
return bytes;
}
void FixSavePos::grow_arrays(int nmax)
{
memory->grow(xold, nmax, 3, "FixSavePos:xold");
}
void FixSavePos::copy_arrays(int i, int j, int delflag)
{
memcpy(xold[j], xold[i], sizeof(double) * 3);
}
void FixSavePos::set_arrays(int i)
{
memset(xold[i], 0, sizeof(double) * 3);
}
int FixSavePos::pack_exchange(int i, double *buf)
{
int m = 0;
buf[m++] = xold[i][0];
buf[m++] = xold[i][1];
buf[m++] = xold[i][2];
return m;
}
int FixSavePos::unpack_exchange(int nlocal, double *buf)
{
int m = 0;
xold[nlocal][0] = buf[m++];
xold[nlocal][1] = buf[m++];
xold[nlocal][2] = buf[m++];
return m;
}
Now, a little bit about memory allocation. We use the Memory class which
is just a bunch of template functions for allocating 1D and 2D
arrays. So you need to add include ``memory.h`` to have access to them.
Finally, if you need to write/read some global information used in
your fix to the restart file, you might do it by setting flag
``restart_global = 1`` in the constructor and implementing methods void
``write_restart(FILE *fp)`` and ``void restart(char *buf)``.
If, in addition, you want to write the per-atom property to restart
files additional settings and functions are needed:
- a fix flag indicating this needs to be set ``restart_peratom = 1;``
- ``atom->add_callback()`` and ``atom->delete_callback()`` must be called
a second time with the final argument set to 1 instead of 0 (indicating
restart processing instead of per-atom data memory management).
- the functions ``void pack_restart(int i, double *buf)`` and
``void unpack_restart(int nlocal, int nth)`` need to be implemented

1354
doc/src/Developer_write_pair.rst Normal file
View File

File diff suppressed because it is too large Load Diff

2
doc/src/Examples.rst
View File

@ -94,8 +94,6 @@ Lowercase directories
+-------------+------------------------------------------------------------------+
| kim | use of potentials from the `OpenKIM Repository <openkim_>`_ |
+-------------+------------------------------------------------------------------+
| latte | examples for using fix latte for DFTB via the LATTE library |
+-------------+------------------------------------------------------------------+
| mdi | use of the MDI package and MolSSI MDI code coupling library |
+-------------+------------------------------------------------------------------+
| meam | MEAM test for SiC and shear (same as shear examples) |

2
doc/src/Howto.rst
View File

@ -23,7 +23,6 @@ General howto
Howto_library
Howto_couple
Howto_mdi
Howto_bpm
Howto_broken_bonds
Settings howto
@ -83,6 +82,7 @@ Packages howto
Howto_spherical
Howto_granular
Howto_body
Howto_bpm
Howto_polarizable
Howto_coreshell
Howto_drude

78
doc/src/Howto_broken_bonds.rst
View File

@ -1,48 +1,56 @@
Broken Bonds
============
Typically, bond interactions persist for the duration of a simulation in
LAMMPS. However, there are some exceptions that allow for bonds to
break, including the :doc:`quartic bond style <bond_quartic>` and the
bond styles in the :doc:`BPM package <Howto_bpm>` which contains the
:doc:`bpm/spring <bond_bpm_spring>` and :doc:`bpm/rotational
<bond_bpm_rotational>` bond styles. In these cases, a bond can be broken
if it is stretched beyond a user-defined threshold. LAMMPS accomplishes
this by setting the bond type to 0, such that the bond force is no
longer computed.
Typically, molecular bond interactions persist for the duration of a
simulation in LAMMPS. However, some commands break bonds dynamically,
including the following:
Users are normally able to weight the contribution of pair forces to atoms
that are bonded using the :doc:`special_bonds command <special_bonds>`.
When bonds break, this is not always the case. For the quartic bond style,
pair forces are always turned off between bonded particles. LAMMPS does
this via a computational sleight-of-hand. It subtracts the pairwise
interaction as part of the bond computation. When the bond breaks, the
subtraction stops. For this to work, the pairwise interaction must always
be computed by the :doc:`pair_style <pair_style>` command, whether the bond
is broken or not. This means that :doc:`special_bonds <special_bonds>` must
be set to 1,1,1. After the bond breaks, the pairwise interaction between the
two atoms is turned on, since they are no longer bonded.
* :doc:`bond_style quartic <bond_quartic>`
* :doc:`fix bond/break <fix_bond_break>`
* :doc:`fix bond/react <fix_bond_react>`
* :doc:`BPM package <Howto_bpm>` bond styles
In the BPM package, one can either turn off all pair interactions between
bonded particles or leave them on, overlaying pair forces on top of bond
forces. To remove pair forces, the special bond list is dynamically
updated. More details can be found on the :doc:`Howto BPM <Howto_bpm>`
page.
A bond can break if it is stretched beyond a user-defined threshold or
more generally if other criteria are met.
Bonds can also be broken by fixes which change bond topology, including
:doc:`fix bond/break <fix_bond_break>` and
:doc:`fix bond/react <fix_bond_react>`. These fixes will automatically
trigger a rebuild of the neighbor list and update special bond data structures
when bonds are broken.
For the quartic bond style, when a bond is broken its bond type is set
to 0 to effectively break it and pairwise forces between the two atoms
in the broken bond are "turned on". Angles, dihedrals, etc cannot be
defined for a system when :doc:`bond_style quartic <bond_quartic>` is
used.
Note that when bonds are dumped to a file via the :doc:`dump local <dump>` command, bonds with type 0 are not included. The
:doc:`delete_bonds <delete_bonds>` command can also be used to query the
status of broken bonds or permanently delete them, e.g.:
Similarly, bond styles in the BPM package are also incompatible with
angles, dihedrals, etc. and when a bond breaks its type is set to zero.
However, in the BPM package one can either turn off all pair interactions
between bonded particles or leave them on, overlaying pair forces on
top of bond forces. To remove pair forces, the special bond list is
dynamically updated. More details can be found on the :doc:`Howto BPM
<Howto_bpm>` page.
The :doc:`fix bond/break <fix_bond_break>` and :doc:`fix bond/react
<fix_bond_react>` commands allow breaking of bonds within a molecular
topology with may also define angles, dihedrals, etc. These commands
update internal topology data structures to remove broken bonds, as
well as the appropriate angle, dihedral, etc interactions which
include the bond. They also trigger a rebuild of the neighbor list
when this occurs, to turn on the appropriate pairwise forces.
Note that when bonds are dumped to a file via the :doc:`dump local
<dump>` command, bonds with type 0 are not included.
The :doc:`delete_bonds <delete_bonds>` command can be used to query
the status of broken bonds with type = 0 or permanently delete them,
e.g.:
.. code-block:: LAMMPS
delete_bonds all stats
delete_bonds all bond 0 remove
The compute :doc:`nbond/atom <compute_nbond_atom>` can also be used
to tally the current number of bonds per atom, excluding broken bonds.
The compute :doc:`count/type <compute_count_type>` command tallies the
current number of bonds (or angles, etc) for each bond (angle, etc)
type. It also tallies broken bonds with type = 0.
The compute :doc:`nbond/atom <compute_nbond_atom>` command tallies the
current number of bonds each atom is part of, excluding broken bonds
with type = 0.

18
doc/src/Howto_couple.rst
View File

@ -12,16 +12,16 @@ LAMMPS can be coupled to other codes in at least 4 different ways. Each
has advantages and disadvantages, which you will have to think about in
the context of your application.
1. Define a new :doc:`fix <fix>` command that calls the other code. In
this scenario, LAMMPS is the driver code. During timestepping, the
fix is invoked, and can make library calls to the other code, which
has been linked to LAMMPS as a library. This is the way the
:ref:`LATTE <PKG-LATTE>` package, which performs density-functional
tight-binding calculations using the `LATTE software
<https://github.com/lanl/LATTE>`_ to compute forces, is interfaced to
LAMMPS. See the :doc:`fix latte <fix_latte>` command for more
1. Define a new :doc:`fix <fix>` or :doc:`compute <compute>` command
that calls the other code. In this scenario, LAMMPS is the driver
code. During timestepping, the fix or compute is invoked, and can
make library calls to the other code, which has been linked to LAMMPS
as a library. This is the way the :ref:`VORONOI <PKG-VORONOI>`
package, which computes Voronoi tesselations using the `Voro++
library <http://math.lbl.gov/voro++>`_, is interfaced to LAMMPS. See
the :doc:`compute voronoi <compute_voronoi_atom>` command for more
details. Also see the :doc:`Modify <Modify>` pages for information
on how to add a new fix to LAMMPS.
on how to add a new fix or compute to LAMMPS.
.. spacer

68
doc/src/Howto_mdi.rst
View File

@ -76,9 +76,16 @@ energy minimizations, or to evaluate the quantum energy and forces for a
series of independent systems. The ``examples/mdi`` directory has
example input scripts for all of these use cases.
The package also has a :doc:`fix mdi/qmmm <fix_mdi_qmmm>` command in
which LAMMPS operates as an MDI driver in conjunction with a quantum
mechanics code as an MDI engine to perform QM/MM simulations. The
LAMMPS input script partitions the system into QM and MM (molecular
mechanics) atoms. As described below the ``examples/QUANTUM`` directory
has examples for coupling to 3 different quantum codes in this manner.
----------
The examples/mdi directory contains Python scripts and LAMMPS input
The ``examples/mdi`` directory contains Python scripts and LAMMPS input
script which use LAMMPS as either an MDI driver or engine, or both.
Currently, 5 example use cases are provided:
@ -119,45 +126,26 @@ as a plugin library.
-------------
Currently, there are at least two quantum DFT codes which have direct MDI
As of March 2023, these are quantum codes with MDI support provided via
Python wrapper scripts included in the LAMMPS distribution. These can
be used with the fix mdi/qm and fix mdi/qmmm commands to perform QM
calculations of an entire system (e.g. AIMD) or QM/MM simulations. See
the ``examples/QUANTUM`` sub-directories for more details:
* LATTE - AIMD only
* PySCF - QM/MM only
* NWChem - AIMD or QM/MM
There are also at least two quantum codes which have direct MDI
support, `Quantum ESPRESSO (QE) <https://www.quantum-espresso.org/>`_
and `INQ <https://qsg.llnl.gov/node/101.html>`_. There are also several
QM codes which have indirect support through QCEngine or i-PI. The
former means they require a wrapper program (QCEngine) with MDI support
which writes/read files to pass data to the quantum code itself. The
list of QCEngine-supported and i-PI-supported quantum codes is on the
`MDI webpage
and `INQ <https://qsg.llnl.gov/node/101.html>`_. There are also
several QM codes which have indirect support through QCEngine or i-PI.
The former means they require a wrapper program (QCEngine) with MDI
support which writes/read files to pass data to the quantum code
itself. The list of QCEngine-supported and i-PI-supported quantum
codes is on the `MDI webpage
<https://molssi-mdi.github.io/MDI_Library/html/index.html>`_.
Here is how to build QE as a stand-alone ``pw.x`` file which can be
used in stand-alone mode:
.. code-block:: bash
git clone --branch mdi_plugin https://github.com/MolSSI-MDI/q-e.git <base_path>/q-e
build the executable pw.x, following the `QE build guide <https://gitlab.com/QEF/q-e/-/wikis/Developers/CMake-build-system>`_
Here is how to build QE as a shared library which can be used in plugin mode,
which results in a ``libqemdi.so`` file in ``<base_path>/q-e/MDI/src``:
.. code-block:: bash
git clone --branch mdi_plugin https://github.com/MolSSI-MDI/q-e.git <base_path>/q-e
cd <base_path>/q-e
./configure --enable-parallel --enable-openmp --enable-shared FFLAGS="-fPIC" FCFLAGS="-fPIC" CFLAGS="-fPIC" foxflags="-fPIC" try_foxflags="-fPIC"
make -j 4 mdi
INQ cannot be built as a stand-alone code; it is by design a library.
Here is how to build INQ as a shared library which can be used in
plugin mode, which results in a ``libinqmdi.so`` file in
``<base_path>/inq/build/examples``:
.. code-block:: bash
git clone --branch mdi --recurse-submodules https://gitlab.com/taylor-a-barnes/inq.git <base_path>/inq
cd <base_path>/inq
mkdir -p build
cd build
../configure --prefix=<install_path>/install
make -j 4
make install
These direct- and indirect-support codes should be usable for full
system calculations (e.g. AIMD). Whether they support QM/MM models
depends on the individual QM code.

2
doc/src/Howto_tip4p.rst
View File

@ -101,7 +101,7 @@ not as part of the pair coefficients.
- 0.52422
* - LJ :math:`\epsilon` of OO (kcal/mole)
- 0.1550
- 0.1577
- 0.21084
- 0.1852
- 0.16275
* - LJ :math:`\sigma` of OO (:math:`\AA`)

12
doc/src/Install_conda.rst
View File

@ -1,13 +1,13 @@
Download an executable for Linux or Mac via Conda
-------------------------------------------------
Download an executable for Linux or macOS via Conda
---------------------------------------------------
Pre-compiled LAMMPS binaries are available for macOS and Linux via the
`Conda <conda_>`_ package management system.
First, one must set up the Conda package manager on your system. Follow the
instructions to install `Miniconda <mini_conda_install_>`_, then create a conda
environment (named `my-lammps-env` or whatever you prefer) for your LAMMPS
install:
First, one must set up the Conda package manager on your system. Follow
the instructions to install `Miniconda <mini_conda_install_>`_, then
create a conda environment (named `my-lammps-env` or whatever you
prefer) for your LAMMPS install:
.. code-block:: bash

21
doc/src/Install_mac.rst
View File

@ -1,12 +1,12 @@
Download an executable for Mac
------------------------------
Download an executable for macOS
--------------------------------
LAMMPS can be downloaded, built, and configured for OS X on a Mac with
`Homebrew <homebrew_>`_. (Alternatively, see the installation
instructions for :doc:`downloading an executable via Conda
<Install_conda>`.) The following LAMMPS packages are unavailable at
this time because of additional requirements not yet met: GPU, KOKKOS,
LATTE, MSCG, MPIIO, POEMS, VORONOI.
LAMMPS can be downloaded, built, and configured for macOS with `Homebrew
<homebrew_>`_. (Alternatively, see the installation instructions for
:doc:`downloading an executable via Conda <Install_conda>`.) The
following LAMMPS packages are unavailable at this time because of
additional requirements not yet met: GPU, KOKKOS, MSCG, MPIIO, POEMS,
VORONOI.
After installing Homebrew, you can install LAMMPS on your system with
the following commands:
@ -15,8 +15,9 @@ the following commands:
brew install lammps
This will install the executables "lammps_serial" and "lammps_mpi", as well as
the LAMMPS "doc", "potentials", "tools", "bench", and "examples" directories.
This will install the executables "lammps_serial" and "lammps_mpi", as
well as the LAMMPS "doc", "potentials", "tools", "bench", and "examples"
directories.
Once LAMMPS is installed, you can test the installation with the
Lennard-Jones benchmark file:

17
doc/src/Install_tarball.rst
View File

@ -2,7 +2,7 @@ Download source and documentation as a tarball
----------------------------------------------
You can download a current LAMMPS tarball from the `download page <download_>`_
of the `LAMMPS website <lws_>`_.
of the `LAMMPS website <lws_>`_ or from GitHub (see below).
.. _download: https://www.lammps.org/download.html
.. _bug: https://www.lammps.org/bug.html
@ -17,21 +17,21 @@ tarball occasionally updated. Feature releases occur every 4 to 8
weeks. The new contents in all feature releases are listed on the `bug
and feature page <bug_>`_ of the LAMMPS homepage.
Both tarballs include LAMMPS documentation (HTML and PDF files)
corresponding to that version.
Tarballs of older LAMMPS versions can also be downloaded from `this page
<older_>`_.
Once you have a tarball, unzip and untar it with the following
Tarballs downloaded from the LAMMPS homepage include the pre-translated
LAMMPS documentation (HTML and PDF files) corresponding to that version.
Once you have a tarball, uncompress and untar it with the following
command:
.. code-block:: bash
tar -xzvf lammps*.tar.gz
This will create a LAMMPS directory with the version date
in its name, e.g. lammps-23Jun18.
This will create a LAMMPS directory with the version date in its name,
e.g. lammps-28Mar23.
----------
@ -45,7 +45,8 @@ with the following command, to create a lammps-<version> directory:
unzip lammps*.zip
This version corresponds to the selected LAMMPS feature or stable
release.
release (as indicated by the matching git tag) and will only contain the
source code and no pre-built documentation.
.. _git: https://github.com/lammps/lammps/releases

2
doc/src/Intro_features.rst
View File

@ -88,7 +88,7 @@ commands)
* charge equilibration (QEq via dynamic, point, shielded, Slater methods)
* coarse-grained potentials: DPD, GayBerne, REsquared, colloidal, DLVO, oxDNA / oxRNA, SPICA
* 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)
* semi-empirical potentials: multi-ion generalized pseudopotential theory (MGPT), second moment tight binding + QEq (SMTB-Q)
* electron force field (eFF, AWPMD)
* bond potentials: harmonic, FENE, Morse, nonlinear, Class II (COMPASS), quartic (breakable), tabulated, scripted
* angle potentials: harmonic, CHARMM, cosine, cosine/squared, cosine/periodic, Class II (COMPASS), tabulated, scripted

17
doc/src/Manual.rst
View File

@ -136,10 +136,21 @@ Indices and tables
:class: note
The HTML version of the manual makes use of advanced features present
in "modern" web browsers. This can lead to incompatibilities with older
web browsers (released more than 4 years ago) and specific vendor browsers
(e.g. Internet Explorer on Windows; Microsoft Edge works well though)
in "modern" web browsers. This leads to incompatibilities with older
web browsers and specific vendor browsers (e.g. Internet Explorer on Windows)
where parts of the pages are not rendered as expected (e.g. the layout is
broken or mathematical expressions not typeset). In that case we
recommend to install/use a different/newer web browser or use
the `PDF version of the manual <https://docs.lammps.org/Manual.pdf>`_.
The following web browser versions have been verified to work as
expected on Linux, macOS, and Windows where available:
- Safari version 11.1 and later
- Firefox version 54 and later
- Chrome version 54 and later
- Opera version 41 and later
- Edge version 80 and later
Also Android version 7.1 and later and iOS version 11 and later have
been verified to render this website as expected.

23
doc/src/Modify.rst
View File

@ -1,23 +1,30 @@
Modifying & extending LAMMPS
****************************
LAMMPS is designed in a modular fashion and to be easy to modify or
extend with new functionality. In fact, about 95% of its source code
are optional. The following pages give basic instructions on what
is required when adding new styles of different kinds to LAMMPS.
LAMMPS has a modular design, so that it is easy to modify or extend with
new functionality. In fact, about 95% of its source code is optional.
The following pages give basic instructions on adding new features to
LAMMPS. More in-depth explanations and documentation of individual
functions and classes are given in :doc:`Developer`.
If you add a new feature to LAMMPS and think it will be of general
interest to other 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 about :doc:`how to
prepare your code for submission <Modify_contribute>` and :doc:`the
style requirements and recommendations <Modify_style>`.
LAMMPS. This process is explained in the following three pages:
* :doc:`how to prepare and submit your code <Modify_contribute>`
* :doc:`requirements for submissions <Modify_requirements>`
* :doc:`style guidelines <Modify_style>`
A summary description of various types of styles in LAMMPS follows.
A discussion of implementing specific styles from scratch is given
in :doc:`writing new styles <Developer_write>`.
.. toctree::
:maxdepth: 1
Modify_overview
Modify_contribute
Modify_requirements
Modify_style
.. toctree::

184
doc/src/Modify_contribute.rst
View File

@ -2,74 +2,59 @@ Submitting new features for inclusion in LAMMPS
===============================================
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.
to be included in 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.
This section contains general information regarding the preparation
and submission of new features to LAMMPS. If you are new to
development in LAMMPS, we recommend you read one of the tutorials on
developing a new :doc:`pair style <Developer_write_pair>` or :doc:`fix
style <Developer_write_fix>` which provide a friendly introduction to
what LAMMPS development entails and common vocabulary used on this
section.
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
easier to integrate your contribution and results in less work for
everybody involved. You are also encouraged to search through the list
of `open issues on GitHub <https://github.com/lammps/lammps/issues>`_
and submit a new issue for a planned feature, so you would not duplicate
the work of others (and possibly get scooped by them) or have your work
duplicated by others.
For any larger modifications or programming project, you are
encouraged to contact the LAMMPS developers ahead of time to discuss
implementation strategies. That will make it easier to integrate your
contribution and typically results in less work for everyone involved.
You are also encouraged to search through the list of `open issues on
GitHub <https://github.com/lammps/lammps/issues>`_ and submit a new
issue for a planned feature, to avoid duplicating work (and possibly
being scooped).
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 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. 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 looking
for help with compiling, installing, or using LAMMPS. Please post a
message to the `LAMMPS forum <https://www.lammps.org/forum.html>`_ for
those purposes.
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).
How quickly your contribution will be integrated can vary widely. It
depends largely on how much effort is required by the LAMMPS
developers to integrate and test it, if any and what kind of changes
to the core code are required, how quickly you can address them, and
how much interest the contribution is to the larger LAMMPS
community. This process can be streamlined by following the
:doc:`requirements <Modify_requirements>` and :doc:`style
guidelines<Modify_style>`. A small, modular, well written
contribution may be integrated within hours, but a complex change that
requires a re-design of a core functionality in LAMMPS can take months
before inclusion (though this is rare).
Submission procedure
@ -78,36 +63,24 @@ 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 development version of LAMMPS and contains all
bug fixes from it.
developer. Before submitting your contribution, you should therefore
first ensure that your added or modified code compiles and works
correctly with the latest 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.
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 are unable
or unwilling to submit via GitHub yourself, you may also send patch
files or full files to the `LAMMPS developers
<https://www.lammps.org/authors.html>`_ and ask them to submit a pull
request on GitHub on your behalf. If this is the case, create a
gzipped tar file of all new or changed 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. This mode of submission may delay the integration
as it depends more on the LAMMPS developers.
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.
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.
External contributions
----------------------
@ -115,11 +88,42 @@ External contributions
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.
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
naming external packages USER-\<name\> so they can be easily
distinguished from packages in the LAMMPS distribution which do not
have the USER- prefix.
Location of files: individual files and packages
------------------------------------------------
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 should be added to one of them. It should fit
into the general purpose of that package. If it does not fit well, it
may be added to one of the EXTRA- packages or the MISC package.
However, if your project includes many 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 create a new package with its own
directory (with a name like FOO). In addition to your new files, the
directory should contain a README text file containing your name and
contact information and a brief description of what your new package
does.
Changes to core LAMMPS files
--------------------------------
If designed correctly, most additions 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 your features involve more substantive
changes to the core LAMMPS files, it is particularly encouraged that
you communicate with the LAMMPS developers early in development.

30
doc/src/Modify_gran_sub_mod.rst
View File

@ -25,7 +25,7 @@ specific implementation. For instance, from the GranSubModNormal class the
GranSubModNormalHooke, GranSubModNormalHertz, and GranSubModNormalJKR classes
are derived which calculate Hookean, Hertzian, or JKR normal forces,
respectively. This modular structure simplifies the addition of new granular
contact models as as one only needs to create a new GranSubMod class without
contact models as one only needs to create a new GranSubMod class without
having to modify the more complex PairGranular, FixGranWall, and GranularModel
classes. Most GranSubMod methods are also already defined by the parent classes
so new contact models typically only require edits to a few relevant methods
@ -80,8 +80,8 @@ There are also several type-specific methods
- Optional method to test when particles are in contact. By default, this is when particles overlap.
* - ``GranSubModNormal->pulloff_distance()``
- Optional method to return the distance at which particles stop interacting. By default, this is when particles no longer overlap.
* - ``GranSubModNormal->calculate_area()``
- Optional method to return the surface area of the contact. By default, this returns the geometric cross section.
* - ``GranSubModNormal->calculate_radius()``
- Optional method to return the radius of the contact. By default, this returns the radius of the geometric cross section.
* - ``GranSubModNormal->set_fncrit()``
- Optional method that defines the critical force to break the contact used by some tangential, rolling, and twisting sub-models. By default, this is the current total normal force including damping.
* - ``GranSubModNormal->calculate_forces()``
@ -105,9 +105,7 @@ set of files ``gran_sub_mod_custom.h``:
#ifdef GranSubMod_CLASS
// clang-format off
GranSubModStyle(hooke/piecewise,
GranSubModNormalHookePiecewise,
NORMAL);
GranSubModStyle(hooke/piecewise,GranSubModNormalHookePiecewise,NORMAL);
// clang-format on
#else
@ -119,15 +117,14 @@ set of files ``gran_sub_mod_custom.h``:
namespace LAMMPS_NS {
namespace Granular_NS {
class GranSubModNormalHookePiecewise : public GranSubModNormal {
public:
GranSubModNormalHookePiecewise(class GranularModel *, class LAMMPS *);
void coeffs_to_local() override;
double calculate_forces();
protected:
double k1, k2, delta_switch;
};
class GranSubModNormalHookePiecewise : public GranSubModNormal {
public:
GranSubModNormalHookePiecewise(class GranularModel *, class LAMMPS *);
void coeffs_to_local() override;
double calculate_forces() override;
protected:
double k1, k2, delta_switch;
};
} // namespace Granular_NS
} // namespace LAMMPS_NS
@ -147,7 +144,8 @@ and ``gran_sub_mod_custom.cpp``
using namespace LAMMPS_NS;
using namespace Granular_NS;
GranSubModNormalHookePiecewise::GranSubModNormalHookePiecewise(GranularModel *gm, LAMMPS *lmp) : GranSubModNormal(gm, lmp)
GranSubModNormalHookePiecewise::GranSubModNormalHookePiecewise(GranularModel *gm, LAMMPS *lmp) :
GranSubModNormal(gm, lmp)
{
num_coeffs = 4;
}

85
doc/src/Modify_overview.rst
View File

@ -1,42 +1,44 @@
Overview
========
The best way to add a new feature to LAMMPS is to find a similar feature
and look at the corresponding source and header files to figure out what
it does. You will need some knowledge of C++ to be able to understand
the high-level structure of LAMMPS and its class organization, but
functions (class methods) that do actual computations are mostly written
in C-style code and operate on simple C-style data structures (vectors
and arrays). A high-level overview of the programming style choices in
LAMMPS is :doc:`given elsewhere <Developer_code_design>`.
The best way to add a new feature to LAMMPS is to find a similar
feature and look at the corresponding source and header files to
figure out what it does. You will need some knowledge of C++ to
understand the high-level structure of LAMMPS and its class
organization. Functions (class methods) that do actual computations
are mostly written in C-style code and operate on simple C-style data
structures (vectors and arrays). A high-level overview of the
programming style choices in LAMMPS is :doc:`given elsewhere
<Developer_code_design>`.
Most of the new features described on the :doc:`Modify <Modify>` doc
page require you to write a new C++ derived class (except for exceptions
described below, where you can make small edits to existing files).
Creating a new class requires 2 files, a source code file (\*.cpp) and a
header file (\*.h). The derived class must provide certain methods to
work as a new option. Depending on how different your new feature is
compared to existing features, you can either derive from the base class
itself, or from a derived class that already exists. Enabling LAMMPS to
invoke the new class is as simple as putting the two source files in the
src directory and re-building LAMMPS.
page require you to write a new C++ derived class (except for
exceptions described below, where you can make small edits to existing
files). Creating a new class requires 2 files, a source code file
(\*.cpp) and a header file (\*.h). The derived class must provide
certain methods to work as a new option. Depending on how different
your new feature is compared to existing features, you can either
derive from the base class itself, or from a derived class that
already exists. Enabling LAMMPS to invoke the new class is as simple
as putting the two source files in the src directory and re-building
LAMMPS.
The advantage of C++ and its object-orientation is that all the code
and variables needed to define the new feature are in the 2 files you
write, and thus should not make the rest of LAMMPS more complex or
cause side-effect bugs.
write. Thus, it should not make the rest of LAMMPS more complex or
cause bugs through unwanted side effects.
Here is a concrete example. Suppose you write 2 files pair_foo.cpp
and pair_foo.h that define a new class PairFoo that computes pairwise
potentials described in the classic 1997 :ref:`paper <Foo>` by Foo, et al.
If you wish to invoke those potentials in a LAMMPS input script with a
command like
Here is a concrete example. Suppose you write 2 files
``pair_foo.cpp`` and ``pair_foo.h`` that define a new class
``PairFoo`` which computes pairwise potentials described in the
classic 1997 :ref:`paper <Foo>` by Foo, *et al.* If you wish to invoke
those potentials in a LAMMPS input script with a command like:
.. code-block:: LAMMPS
pair_style foo 0.1 3.5
then your pair_foo.h file should be structured as follows:
then your ``pair_foo.h`` file should be structured as follows:
.. code-block:: c++
@ -51,28 +53,27 @@ then your pair_foo.h file should be structured as follows:
#endif
where "foo" is the style keyword in the pair_style command, and
PairFoo is the class name defined in your pair_foo.cpp and pair_foo.h
files.
``PairFoo`` is the class name defined in your ``pair_foo.cpp`` and
``pair_foo.h`` files.
When you re-build LAMMPS, your new pairwise potential becomes part of
the executable and can be invoked with a pair_style command like the
example above. Arguments like 0.1 and 3.5 can be defined and
processed by your new class.
As illustrated by this example pair style, many kinds of options are
referred to in the LAMMPS documentation as the "style" of a particular
command.
As illustrated by this example, many features referred to in the
LAMMPS documentation are called a "style" of a particular command.
The :doc:`Modify page <Modify>` lists all the common styles in LAMMPS,
and discusses the header file for the base class that these styles are
derived from. Public variables in that file are ones used and set by
the derived classes which are also used by the base class. Sometimes
they are also used by the rest of LAMMPS. Pure functions, which means
functions declared as virtual in the base class header file which are
also set to 0, are functions you **must** implement in your new derived
class to give it the functionality LAMMPS expects. Virtual functions
that are not set to 0 are functions you may override or not. Those
are usually defined with an empty function body.
and discusses the header file for the base class that these styles
derive from. Public variables in that file can be used and set by the
derived classes, and may also be used by the base class. Sometimes
they are also accessed by the rest of LAMMPS. Pure functions, which
means functions declared as virtual in the base class header file and
which are also set to 0, are functions you **must** implement in your
new derived class to give it the functionality LAMMPS expects. Virtual
functions that are not set to 0 are functions you may override or not.
Those are usually defined with an empty function body.
Additionally, new output options can be added directly to the
thermo.cpp, dump_custom.cpp, and variable.cpp files. These are also
@ -85,9 +86,9 @@ functionality:
post-processing step. Many computations are more easily and more
quickly done that way.
* Do not try to do anything within the timestepping of a run that is not
parallel. For example do not accumulate a bunch of data on a single
processor and analyze it. You run the risk of seriously degrading
the parallel efficiency this way.
parallel. For example, do not accumulate a bunch of data on a single
processor and analyze it. That would run the risk of seriously degrading
the parallel efficiency.
* If your new feature reads arguments or writes output, make sure you
follow the unit conventions discussed by the :doc:`units <units>`
command.

17
doc/src/Modify_pair.rst
View File

@ -2,11 +2,11 @@ Pair styles
===========
Classes that compute pairwise non-bonded interactions are derived from
the Pair class. In LAMMPS, pairwise calculation include many-body
potentials such as EAM, Tersoff, or ReaxFF where particles interact
without an explicit bond topology but include interactions beyond
pairwise non-bonded contributions. New styles can be created to add
support for additional pair potentials to LAMMPS. When the
the ``Pair`` class. In LAMMPS, pairwise force calculations include
many-body potentials such as EAM, Tersoff, or ReaxFF where particles
interact without an explicit bond topology but include interactions
beyond pairwise non-bonded contributions. New styles can be created to
add support for additional pair potentials to LAMMPS. When the
modifications are small, sometimes it is more effective to derive from
an existing pair style class. This latter approach is also used by
:doc:`Accelerator packages <Speed_packages>` where the accelerated style
@ -15,10 +15,13 @@ names differ from their base classes by an appended suffix.
The file ``src/pair_lj_cut.cpp`` is an example of a Pair class with a
very simple potential function. It includes several optional methods to
enable its use with :doc:`run_style respa <run_style>` and :doc:`compute
group/group <compute_group_group>`.
group/group <compute_group_group>`. :doc:`Developer_write_pair` contains
a detailed discussion of writing new pair styles from scratch, and how
simple and more complex pair styles can be implemented with examples
from existing pair styles.
Here is a brief list of some the class methods in the Pair class that
*must* be or *may* be overridden in a derived class.
*must* be or *may* be overridden in a derived class for a new pair style.
+---------------------------------+---------------------------------------------------------------------+
| Required | "pure" methods that *must* be overridden in a derived class |

384
doc/src/Modify_requirements.rst Normal file
View File

@ -0,0 +1,384 @@
Requirements for contributions to LAMMPS
========================================
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 provide 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 who may not be professionally trained programmers or
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 is necessary to
follow established guidelines when accepting new contributions while
also working at the same time to improve the existing code.
The following requirements and recommendations are provided as a
guide. They indicate which individual 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 you need assistance
in implementing the (strict) requirements for your contributions.
Requirements include:
* :ref:`Licensing requirements <ReqLicense>` (strict)
* :ref:`Integration testing <ReqIntegrationTesting>` (strict)
* :ref:`Documentation <ReqDocumentation>` (strict)
* :ref:`Programming language standards <ReqProgrammingStandards>` (strict)
* :ref:`Build system <ReqBuildSystem>` (strict)
* :ref:`Command or style names <ReqNaming>` (strict)
* :ref:`Programming style requirements <ReqProgrammingStyle>` (varied)
* :ref:`Examples <ReqExamples>` (preferred)
* :ref:`Error or warning messages and explanations <ReqErrorMessages>` (preferred)
* :ref:`Citation reminder <ReqCitation>` (optional)
* :ref:`Testing <ReqUnitTesting>` (optional)
.. _ReqLicense:
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. We also have a version of LAMMPS under LGPL 2.1 terms which
is available on request; this will usually be the latest available or
a previous stable version with a few LGPL 2.1 incompatible files
removed. More details are found on the :doc:`LAMMPS open-source
license page <Intro_opensource>`.
Your new source files should have the LAMMPS copyright and GPL notice,
followed by your name and email address at the top, like other
user-contributed LAMMPS source files.
Contributions may be under a different license as 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 licensing mode may complicate including
the contribution in binary packages.
.. _ReqIntegrationTesting:
Integration testing (strict)
----------------------------
Where possible we use available continuous integration tools to search
for common programming mistakes, portability limitations, incompatible
formatting, and undesired side effects. Contributed code 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. The translation of the
documentation to HTML and PDF is also tested.
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.
.. _ReqDocumentation:
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 should be written in American English and the
.rst file must only use ASCII characters, so it can be cleanly
translated to PDF files (via `sphinx <https://www.sphinx-doc.org>`_ and
PDFLaTeX). Special characters may be included via embedded math
expression typeset in a LaTeX subset.
.. _rst: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.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, some lists
describing packages must also be updated as well as a package specific
description added. Likewise, if necessary, some package specific
build instructions should be included.
As appropriate, the text files with the documentation can include
inline mathematical expressions or figures (see ``doc/JPG`` for
examples). Additional PDF files with further details may also be
included; see ``doc/PDF`` for examples. 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 package. See other command doc files for
examples of how to do this.
Please run at least "make html" and "make spelling" from within the
doc/src directory, 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 to 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.
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 of models
that require use of multiple commands.
As a 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.
.. _ReqProgrammingStandards:
Programming language standards (strict)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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 improve 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, a collection of
convenient :doc:`utility functions and classes <Developer_utils>` for
recurring tasks and a collection of :doc:`platform neutral functions
<Developer_platform>` for improved portability are provided.
Contributions with code requiring more recent C++ standards are only
accepted as packages with the post C++11 standard code confined to the
package so that it is optional.
Included Fortran code has to be compatible with the Fortran 2003
standard. Since not all platforms supported by LAMMPS provide good
support for compiling Fortran files, it should be considered to rewrite
these parts as C++ code, if possible and thus allow for a wider adoption
of the contribution. As of January 2023, all previously included
Fortran code for the LAMMPS executable has been replaced by equivalent
C++ code.
Python code must be compatible with Python 3.5 and later. Large parts
of 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 older programming language standards is very
important to maintain portability and availability of LAMMPS on many
platforms. This applies especially to HPC cluster environments, which
tend to be running older software stacks and where LAMMPS users may be
required to use those older tools for access to advanced hardware
features or not have the option to install newer compilers or libraries.
.. _ReqBuildSystem:
Build system (strict)
---------------------
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>`. Therefore, your contribution must be
compatible with and support both build systems.
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.
.. _ReqNaming:
Command or style names, file names, and keywords (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" in the header file would
then be ``LMP_COMPUTE_SOME_NAME_H`` and the class name
``ComputeSomeName``.
.. _ReqProgrammingStyle:
Programming style requirements (varied)
---------------------------------------
To maintain source code consistency across contributions from many
people, there are various programming style requirements for
contributions to LAMMPS. Some of these requirements are strict and
must be followed, while others are only preferred and thus may be
skipped. An in-depth discussion of the style guidelines is provided
in the :doc:`programming style doc page <Modify_style>`.
.. _ReqExamples:
Examples (preferred)
--------------------
For many new features, 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 include
under the examples or examples/PACKAGES directory and are further
described on the :doc:`examples page <Examples>`. Guidelines for
input scripts include:
- 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 it complicates comparisons between different runs
- 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
.. _ReqErrorMessages:
Error or warning messages and explanations (preferred)
------------------------------------------------------
.. versionchanged:: 4May2022
Starting with LAMMPS version 4 May 2022, the LAMMPS developers have
agreed on a new policy for error and warning messages.
Previously, all error and warning strings were supposed to be listed in
the class header files with an explanation. Those would then be
regularly "harvested" and transferred to alphabetically sorted lists in
the manual. To avoid excessively long lists and to reduce effort, this
came with a requirement to have rather generic error messages (e.g.
"Illegal ... command"). To identify the specific cause, the name of the
source file and the line number of the error location would be printed,
so that one could look up the cause by reading the source code.
The new policy encourages more specific error messages that ideally
indicate the cause directly, and requiring no further lookup. This is
aided by the `{fmt} library <https://fmt.dev>`_ enabling Error class
methods that take a variable number of arguments and an error text that
will be treated like a {fmt} syntax format string. Error messages should
still preferably be kept to a single line or two lines at most.
For more complex explanations or errors that have multiple possible
reasons, a paragraph should be added to the `Error_details` page with an
error code reference (e.g. ``.. _err0001:``) then the utility function
:cpp:func:`utils::errorurl() <LAMMPS_NS::utils::errorurl>` can be used
to generate a URL that will directly lead to that paragraph. An error
for missing arguments can be easily generated using the
:cpp:func:`utils::missing_cmd_args()
<LAMMPS_NS::utils::missing_cmd_args>` convenience function.
An example for this approach would be the
``src/read_data.cpp`` and ``src/atom.cpp`` files that implement the
:doc:`read_data <read_data>` and :doc:`atom_modify <atom_modify>`
commands and that may create :ref:`"Unknown identifier in data file" <err0001>`
errors that may have multiple possible reasons which complicates debugging,
and thus require some additional explanation.
The transformation of existing LAMMPS code to this new scheme is
ongoing. Given the size of the LAMMPS code base, it will take a
significant amount of time to complete. For new code, however,
following the new approach is strongly preferred. The expectation is
that the new scheme will make understanding errors easier for LAMMPS
users, developers, and maintainers.
.. _ReqCitation:
Citation reminder (optional)
-----------------------------
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, then
LAMMPS (by default) 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 so 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 source 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.
.. _ReqUnitTesting:
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.

587
doc/src/Modify_style.rst
View File

@ -1,350 +1,58 @@
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 <https://www.sphinx-doc.org>`_ and PDFLaTeX).
Special characters may be included via embedded math expression typeset
in a LaTeX subset.
.. _rst: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.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.
You can check for these issues with the python scripts in the
:ref:`"tools/coding_standard" <coding_standard>` folder. When run
normally with a source file or a source folder as argument, they will
list all non-conforming lines. By adding the `-f` flag to the command
line, they will modify the flagged files to try removing the detected
issues.
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.
Error or warning messages and explanations (preferred)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionchanged:: 4May2022
Starting with LAMMPS version 4 May 2022 the LAMMPS developers have
agreed on a new policy for error and warning messages.
Previously, all error and warning strings were supposed to be listed in
the class header files with an explanation. Those would then be
regularly "harvested" and transferred to alphabetically sorted lists in
the manual. To avoid excessively long lists and to reduce effort, this
came with a requirement to have rather generic error messages (e.g.
"Illegal ... command"). To identify the specific cause, the name of the
source file and the line number of the error location would be printed,
so that one could look up the cause by reading the source code.
The new policy encourages more specific error messages that ideally
indicate the cause directly and no further lookup would be needed.
This is aided by using the `{fmt} library <https://fmt.dev>`_ to convert
the Error class commands so that they take a variable number of arguments
and error text will be treated like a {fmt} syntax format string.
Error messages should still kept to a single line or two lines at the most.
For more complex explanations or errors that have multiple possible
reasons, a paragraph should be added to the `Error_details` page with an
error code reference (e.g. ``.. _err0001:``) then the utility function
:cpp:func:`utils::errorurl() <LAMMPS_NS::utils::errorurl>` can be used
to generate an URL that will directly lead to that paragraph. An error
for missing arguments can be easily generated using the
:cpp:func:`utils::missing_cmd_args()
<LAMMPS_NS::utils::missing_cmd_args>` convenience function.
The transformation of existing LAMMPS code to this new scheme is ongoing
and - given the size of the LAMMPS source code - will take a significant
amount of time until completion. However, for new code following the
new approach is strongly preferred. The expectation is that the new
scheme will make it easier for LAMMPS users, developers, and
maintainers.
An example for this approach would be the
``src/read_data.cpp`` and ``src/atom.cpp`` files that implement the
:doc:`read_data <read_data>` and :doc:`atom_modify <atom_modify>`
commands and that may create :ref:`"Unknown identifier in data file" <err0001>`
errors that seem difficult to debug for users because they may have
one of multiple possible reasons, and thus require some additional explanations.
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 a collection of
convenient :doc:`utility functions and classes <Developer_utils>` for
recurring tasks and a collection of
:doc:`platform neutral functions <Developer_platform>` for improved
portability 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 and availability of LAMMPS on many
platforms. This applies especially to HPC cluster environments, which
tend to be running older software stacks and LAMMPS users may be
required to use those older tools for access to advanced hardware
features or not have the option to install newer compilers or libraries.
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
LAMMPS programming style
========================
The aim of the LAMMPS developers is to use 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. This page provides a list of standard style
choices used in LAMMPS. Some of these standards are required, while
others are just preferred. Following these conventions will make it
much easier to integrate your contribution. If you are uncertain,
please ask.
The files `pair_lj_cut.h`, `pair_lj_cut.cpp`, `utils.h`, and
`utils.cpp` may serve as representative examples.
Include files (varied)
^^^^^^^^^^^^^^^^^^^^^^
- 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.
- 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 only be the
header for the base class. Instead, any include statements should
be put in 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.
- System headers or headers from installed libraries are included with
angular brackets (example: ``#include <vector>``), while local
include files 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
@ -352,34 +60,70 @@ you are uncertain, please ask.
- 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
- System header files from the C++ or C standard library followed by
an empty line
- ``using namespace LAMMPS_NS`` or other namespace imports.
Whitespace (preferred)
^^^^^^^^^^^^^^^^^^^^^^
Source files should not contain TAB characters unless required by the
syntax (e.g. in makefiles) and no trailing whitespace. Text files
should have 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 to Unix-style line endings. The
last line of text files include a line ending.
You can check for these issues with the python scripts in the
:ref:`"tools/coding_standard" <coding_standard>` folder. When run
normally with a source file or a source folder as argument, they will
list all non-conforming lines. By adding the `-f` flag to the command
line, they will modify the flagged files to try to remove the detected
issues.
Placement of braces (strongly preferred)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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 hard-to-read or otherwise
undesirable output may be protected with placing a pair `//
clang-format off` and `// clang-format on` comments around that block.
Miscellaneous standards (varied)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- I/O is done via the C-style stdio library and **not** iostreams.
- Do not use so-called "alternative tokens" like ``and``, ``or``,
``not`` and similar, but rather use the corresponding operators
``&&``, ``||``, and ``!``. The alternative tokens are not available
by default on all compilers, and also we want to maintain a consistent
programming style.
by default on all compilers.
- 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.
- Output to the screen and the logfile should use the corresponding
FILE pointers and only be done on MPI rank 0. Use the
:cpp:func:`utils::logmesg` convenience function where possible.
- Usage of C++11 `virtual`, `override`, `final` keywords: Please follow the
`C++ Core Guideline C.128 <https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rh-override>`_.
- Usage of C++11 `virtual`, `override`, `final` keywords: Please
follow the `C++ Core Guideline C.128
<https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rh-override>`_.
That means, you should only use `virtual` to declare a new virtual
function, `override` to indicate you are overriding an existing virtual
function, and `final` to prevent any further overriding.
function, `override` to indicate you are overriding an existing
virtual function, and `final` to prevent any further overriding.
- Trivial destructors: Prefer not writing destructors when they are empty and `default`.
- Trivial destructors: Do not write destructors when they are empty
and `default`.
.. code-block:: c++
// don't write destructors for A or B like this
class A : protected Pointers {
public:
A();
@ -393,6 +137,7 @@ you are uncertain, please ask.
};
// instead, let the compiler create the implicit default destructor by not writing it
class A : protected Pointers {
public:
A();
@ -403,37 +148,11 @@ you are uncertain, please ask.
B();
};
- 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:
ClassName)`` macros it is required to have this macro embedded with
a pair of ``// clang-format off``, ``// clang-format on`` comments
and the line must be terminated with a semicolon (;). Example:
.. code-block:: c++
@ -446,92 +165,10 @@ you are uncertain, please ask.
#ifndef LMP_RUN_H
[...]
You may also use ``// clang-format on/off`` throughout your files
to protect individual sections from being reformatted.
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.
- All files should have 0644 permissions, i.e. writable by the user
only and readable by all and no executable permissions. Executable
permissions (0755) should only be for shell scripts or python or
similar scripts for interpreted script languages.

38
doc/src/Packages_details.rst
View File

@ -67,7 +67,6 @@ page gives those details.
* :ref:`KOKKOS <PKG-KOKKOS>`
* :ref:`KSPACE <PKG-KSPACE>`
* :ref:`LATBOLTZ <PKG-LATBOLTZ>`
* :ref:`LATTE <PKG-LATTE>`
* :ref:`LEPTON <PKG-LEPTON>`
* :ref:`MACHDYN <PKG-MACHDYN>`
* :ref:`MANIFOLD <PKG-MANIFOLD>`
@ -1357,43 +1356,6 @@ The LATBOLTZ package requires that LAMMPS is build in :ref:`MPI parallel mode <s
----------
.. _PKG-LATTE:
LATTE package
-------------
**Contents:**
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 website:
`https://github.com/lanl/LATTE <latte-home_>`_. A brief technical
description is given with the :doc:`fix latte <fix_latte>` command.
.. _latte-home: https://github.com/lanl/LATTE
**Authors:** Christian Negre (LANL) and Steve Plimpton (Sandia). LATTE
itself is developed at Los Alamos National Laboratory by Marc
Cawkwell, Anders Niklasson, and Christian Negre.
**Install:**
This package has :ref:`specific installation instructions <latte>` on
the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
* src/LATTE: filenames -> commands
* src/LATTE/README
* lib/latte/README
* :doc:`fix latte <fix_latte>`
* examples/latte
* `LAMMPS-LATTE tutorial <https://github.com/lanl/LATTE/wiki/Using-LATTE-through-LAMMPS>`_
----------
.. _PKG-LEPTON:
LEPTON package

5
doc/src/Packages_list.rst
View File

@ -233,11 +233,6 @@ whether an extra library is needed to build and use the package:
- :doc:`fix lb/fluid <fix_lb_fluid>`
- PACKAGES/latboltz
- no
* - :ref:`LATTE <PKG-LATTE>`
- quantum DFTB forces via LATTE
- :doc:`fix latte <fix_latte>`
- latte
- ext
* - :ref:`LEPTON <PKG-LEPTON>`
- evaluate strings as potential function
- :doc:`pair_style lepton <pair_lepton>`

18
doc/src/Python_install.rst
View File

@ -43,19 +43,20 @@ folder that the dynamic loader searches or inside of the installed
Compile LAMMPS with either :doc:`CMake <Build_cmake>` or the
:doc:`traditional make <Build_make>` procedure in :ref:`shared
mode <exe>`. After compilation has finished type (in the
mode <exe>`. After compilation has finished, type (in the
compilation folder):
.. code-block:: bash
make install-python
This will try to build a so-called (binary) 'wheel', a compressed
binary python package and then install it with the python package
manager 'pip'. Installation will be attempted into a system-wide
``site-packages`` folder and if that fails into the corresponding
folder in the user's home directory. For a system-wide installation you
would have to gain superuser privilege, e.g. though ``sudo``
This will try to build a so-called (binary) wheel file, a
compressed binary python package and then install it with the
python package manager 'pip'. Installation will be attempted into
a system-wide ``site-packages`` folder and if that fails into the
corresponding folder in the user's home directory. For a
system-wide installation you usually would have to gain superuser
privilege first, e.g. though ``sudo``
+------------------------+----------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
@ -106,10 +107,11 @@ folder that the dynamic loader searches or inside of the installed
.. code-block:: bash
python install.py -p <python package> -l <shared library> [-n]
python install.py -p <python package> -l <shared library> -v <version.h file> [-n]
* The ``-p`` flag points to the ``lammps`` Python package folder to be installed,
* the ``-l`` flag points to the LAMMPS shared library file to be installed,
* the ``-v`` flag points to the LAMMPS version header file to extract the version date,
* and the optional ``-n`` instructs the script to only build a wheel file
but not attempt to install it.

10
doc/src/Speed_kokkos.rst
View File

@ -285,6 +285,16 @@ one or more nodes, each with two GPUs:
settings. Experimenting with its options can provide a speed-up for
specific calculations. For example:
.. note::
The default binsize for :doc:`atom sorting <atom_modify>` on GPUs
is equal to the default CPU neighbor binsize (i.e. 2x smaller than the
default GPU neighbor binsize). When running simple pair-wise
potentials like Lennard Jones on GPUs, using a 2x larger binsize for
atom sorting (equal to the default GPU neighbor binsize) and a more
frequent sorting than default (e.g. sorting every 100 time steps
instead of 1000) may improve performance.
.. code-block:: bash
mpirun -np 2 lmp_kokkos_cuda_openmpi -k on g 2 -sf kk -pk kokkos newton on neigh half binsize 2.8 -in in.lj # Newton on, half neighbor list, set binsize = neighbor ghost cutoff

6
doc/src/Tools.rst
View File

@ -883,9 +883,9 @@ dependencies and redirects the download to the local cache.
phonon tool
------------------------
The phonon subdirectory contains a post-processing tool useful for
analyzing the output of the :doc:`fix phonon <fix_phonon>` command in
the PHONON package.
The phonon subdirectory contains a post-processing tool, *phana*, useful
for analyzing the output of the :doc:`fix phonon <fix_phonon>` command
in the PHONON package.
See the README file for instruction on building the tool and what
library it needs. And see the examples/PACKAGES/phonon directory

22
doc/src/angle_dipole.rst
View File

@ -28,15 +28,15 @@ The *dipole* angle style is used to control the orientation of a dipolar
atom within a molecule :ref:`(Orsi) <Orsi>`. Specifically, the *dipole* angle
style restrains the orientation of a point dipole :math:`\mu_j` (embedded in atom
:math:`j`) with respect to a reference (bond) vector
:math:`\vec{r_{ij}} = \vec{r_i} - \vec{r_j}`, where :math:`i` is another atom of
:math:`\vec{r}_{ij} = \vec{r}_i - \vec{r}_j`, where :math:`i` is another atom of
the same molecule (typically, :math:`i` and :math:`j` are also covalently bonded).
It is convenient to define an angle gamma between the 'free' vector :math:`\vec{\mu_j}`
and the reference (bond) vector :math:`\vec{r_{ij}}`:
It is convenient to define an angle gamma between the 'free' vector :math:`\vec{\mu}_j`
and the reference (bond) vector :math:`\vec{r}_{ij}`:
.. math::
\cos\gamma = \frac{\vec{\mu_j}\cdot\vec{r_{ij}}}{\mu_j\,r_{ij}}
\cos\gamma = \frac{\vec{\mu}_j\cdot\vec{r}_{ij}}{\mu_j\,r_{ij}}
The *dipole* angle style uses the potential:
@ -53,23 +53,23 @@ potential using the 'chain rule' as in appendix C.3 of
.. math::
\vec{T_j} = \frac{2K(\cos\gamma - \cos\gamma_0)}{\mu_j\,r_{ij}}\, \vec{r_{ij}} \times \vec{\mu_j}
\vec{T}_j = \frac{2K(\cos\gamma - \cos\gamma_0)}{\mu_j\,r_{ij}}\, \vec{r}_{ij} \times \vec{\mu}_j
Example: if :math:`\gamma_0` is set to 0 degrees, the torque generated by
the potential will tend to align the dipole along the reference
direction defined by the (bond) vector :math:`\vec{r_{ij}}` (in other words, :math:`\vec{\mu_j}` is
direction defined by the (bond) vector :math:`\vec{r}_{ij}` (in other words, :math:`\vec{\mu}_j` is
restrained to point towards atom :math:`i`).
The dipolar torque :math:`\vec{T_j}` must be counterbalanced in order to conserve
The dipolar torque :math:`\vec{T}_j` must be counterbalanced in order to conserve
the local angular momentum. This is achieved via an additional force
couple generating a torque equivalent to the opposite of :math:`\vec{T_j}`:
couple generating a torque equivalent to the opposite of :math:`\vec{T}_j`:
.. math::
-\vec{T_j} & = \vec{r_{ij}} \times \vec{F_i} \\
\vec{F_j} & = -\vec{F_i}
-\vec{T}_j & = \vec{r}_{ij} \times \vec{F}_i \\
\vec{F}_j & = -\vec{F}_i
where :math:`\vec{F_i}` and :math:`\vec{F_j}` are applied on atoms :math:`i`
where :math:`\vec{F}_i` and :math:`\vec{F}_j` are applied on atoms :math:`i`
and :math:`j`, respectively.
The following coefficients must be defined for each angle type via the

7
doc/src/atom_modify.rst
View File

@ -153,6 +153,13 @@ cache locality will be undermined.
order of atoms in a :doc:`dump <dump>` file will also typically change
if sorting is enabled.
.. note::
When running simple pair-wise potentials like Lennard Jones on GPUs
with the KOKKOS package, using a larger binsize (e.g. 2x larger than
default) and a more frequent reordering than default (e.g. every 100
time steps) may improve performance.
Restrictions
""""""""""""

11
doc/src/bond_bpm_rotational.rst
View File

@ -10,7 +10,7 @@ Syntax
bond_style bpm/rotational keyword value attribute1 attribute2 ...
* optional keyword = *overlay/pair* or *store/local* or *smooth*
* optional keyword = *overlay/pair* or *store/local* or *smooth* or *break/no*
.. parsed-literal::
@ -30,6 +30,9 @@ Syntax
*smooth* value = *yes* or *no*
smooths bond forces near the breaking point
*break/no*
indicates that bonds should not break during a run
Examples
""""""""
@ -140,6 +143,12 @@ the *overlay/pair* keyword. These settings require specific
restrictions. Further details can be found in the `:doc: how to
<Howto_BPM>` page on BPMs.
.. versionadded:: 28Mar2023
If the *break/no* keyword is used, then LAMMPS assumes bonds should not break
during a simulation run. This will prevent some unnecessary calculation.
However, if a bond does break, it will trigger an error.
If the *store/local* keyword is used, an internal fix will track bonds that
break during the simulation. Whenever a bond breaks, data is processed
and transferred to an internal fix labeled *fix_ID*. This allows the

20
doc/src/bond_bpm_spring.rst
View File

@ -10,7 +10,7 @@ Syntax
bond_style bpm/spring keyword value attribute1 attribute2 ...
* optional keyword = *overlay/pair* or *store/local* or *smooth*
* optional keyword = *overlay/pair* or *store/local* or *smooth* or *break/no*
.. parsed-literal::
@ -30,6 +30,9 @@ Syntax
*smooth* value = *yes* or *no*
smooths bond forces near the breaking point
*break/no*
indicates that bonds should not break during a run
Examples
""""""""
@ -47,7 +50,7 @@ Description
.. versionadded:: 4May2022
The *bpm/spring* bond style computes forces and torques based on
The *bpm/spring* bond style computes forces based on
deviations from the initial reference state of the two atoms. The
reference state is stored by each bond when it is first computed in
the setup of a run. Data is then preserved across run commands and is
@ -56,7 +59,8 @@ the system will not reset the reference state of a bond.
This bond style only applies central-body forces which conserve the
translational and rotational degrees of freedom of a bonded set of
particles. The force has a magnitude of
particles based on a model described by Clemmer and Robbins
:ref:`(Clemmer) <fragment-Clemmer>`. The force has a magnitude of
.. math::
@ -105,6 +109,12 @@ the *overlay/pair* keyword. These settings require specific
restrictions. Further details can be found in the `:doc: how to
<Howto_BPM>` page on BPMs.
.. versionadded:: 28Mar2023
If the *break/no* keyword is used, then LAMMPS assumes bonds should not break
during a simulation run. This will prevent some unnecessary calculation.
However, if a bond does break, it will trigger an error.
If the *store/local* keyword is used, an internal fix will track bonds that
break during the simulation. Whenever a bond breaks, data is processed
and transferred to an internal fix labeled *fix_ID*. This allows the
@ -200,6 +210,10 @@ The option defaults are *smooth* = *yes*
----------
.. _fragment-Clemmer:
**(Clemmer)** Clemmer and Robbins, Phys. Rev. Lett. (2022).
.. _Groot4:
**(Groot)** Groot and Warren, J Chem Phys, 107, 4423-35 (1997).

2
doc/src/bond_harmonic_restrain.rst
View File

@ -21,7 +21,7 @@ Examples
Description
"""""""""""
.. versionadded:: TBD
.. versionadded:: 28Mar2023
The *harmonic/restrain* bond style uses the potential

14
doc/src/bond_style.rst
View File

@ -32,13 +32,13 @@ Set the formula(s) LAMMPS uses to compute bond interactions between
pairs of atoms. In LAMMPS, a bond differs from a pairwise
interaction, which are set via the :doc:`pair_style <pair_style>`
command. Bonds are defined between specified pairs of atoms and
remain in force for the duration of the simulation (unless the bond
breaks which is possible in some bond potentials). The list of bonded
atoms is read in by a :doc:`read_data <read_data>` or
:doc:`read_restart <read_restart>` command from a data or restart file.
By contrast, pair potentials are typically defined between all pairs
of atoms within a cutoff distance and the set of active interactions
changes over time.
remain in force for the duration of the simulation (unless new bonds
are created or existing bonds break, which is possible in some fixes
and bond potentials). The list of bonded atoms is read in by a
:doc:`read_data <read_data>` or :doc:`read_restart <read_restart>`
command from a data or restart file. By contrast, pair potentials are
typically defined between all pairs of atoms within a cutoff distance
and the set of active interactions changes over time.
Hybrid models where bonds are computed using different bond potentials
can be setup using the *hybrid* bond style.

1
doc/src/comm_modify.rst
View File

@ -69,6 +69,7 @@ For many systems this is an efficient algorithm, but for systems with
widely varying cutoffs for different type pairs, the *multi* or *multi/old* mode can
be faster. In *multi*, each atom is assigned to a collection which should
correspond to a set of atoms with similar interaction cutoffs.
See the :doc:`neighbor <neighbor>` command for a detailed description of collections.
In this case, each atom collection is assigned its own distance
cutoff for communication purposes, and fewer atoms will be
communicated. in *multi/old*, a similar technique is used but atoms

1
doc/src/compute.rst
View File

@ -200,6 +200,7 @@ The individual style names on the :doc:`Commands compute <Commands_compute>` pag
* :doc:`com/chunk <compute_com_chunk>` - center of mass for each chunk
* :doc:`contact/atom <compute_contact_atom>` - contact count for each spherical particle
* :doc:`coord/atom <compute_coord_atom>` - coordination number for each atom
* :doc:`count/type <compute_count_type>` - count of atoms or bonds by type
* :doc:`damage/atom <compute_damage_atom>` - Peridynamic damage for each atom
* :doc:`dihedral <compute_dihedral>` - energy of each dihedral sub-style
* :doc:`dihedral/local <compute_dihedral_local>` - angle of each dihedral

130
doc/src/compute_count_type.rst Normal file
View File

@ -0,0 +1,130 @@
.. index:: compute count/type
compute count/type command
==========================
Syntax
""""""
.. code-block:: LAMMPS
compute ID group-ID count/type mode
* ID, group-ID are documented in :doc:`compute <compute>` command
* count/type = style name of this compute command
* mode = {atom} or {bond} or {angle} or {dihedral} or {improper}
Examples
""""""""
.. code-block:: LAMMPS
compute 1 all count/type atom
compute 1 flowmols count/type bond
Description
"""""""""""
.. versionadded:: TBD
Define a computation that counts the current number of atoms for each
atom type. Or the number of bonds (angles, dihedrals, impropers) for
each bond (angle, dihedral, improper) type.
The former can be useful if atoms are added to or deleted from the
system in random ways, e.g. via the :doc:`fix deposit <fix_deposit>`,
:doc:`fix pour <fix_pour>`, or :doc:`fix evaporate <fix_evaporate>`
commands. The latter can be useful in reactive simulations where
molecular bonds are broken or created, as well as angles, dihedrals,
impropers.
Note that for this command, bonds (angles, etc) are the topological
kind enumerated in a data file, initially read by the :doc:`read_data
<read_data>` command or defined by the :doc:`molecule <molecule>`
command. They do not refer to implicit bonds defined on-the-fly by
bond-order or reactive pair styles based on the current conformation
of small clusters of atoms.
These commands can turn off topological bonds (angles, etc) by setting
their bond (angle, etc) types to negative values. This command
includes the turned-off bonds (angles, etc) in the count for each
type:
* :doc:`fix shake <fix_shake>`
* :doc:`delete_bonds <delete_bonds>`
These commands can create and/or break topological bonds (angles,
etc). In the case of breaking, they remove the bond (angle, etc) from
the system, so that they no longer exist (:doc:`bond_style quartic
<bond_quartic>` and :doc:`BPM bond styles <Howto_bpm>` are exceptions,
see the discussion below). Thus they are not included in the counts
for each type:
* :doc:`delete_bonds remove <delete_bonds>`
* :doc:`bond_style quartic <bond_quartic>`
* :doc:`fix bond/react <fix_bond_react>`
* :doc:`fix bond/create <fix_bond_create>`
* :doc:`fix bond/break <fix_bond_break>`
* :doc:`BPM package <Howto_bpm>` bond styles
----------
If the {mode} setting is {atom} then the count of atoms for each atom
type is tallied. Only atoms in the specified group are counted.
If the {mode} setting is {bond} then the count of bonds for each bond
type is tallied. Only bonds with both atoms in the specified group
are counted.
For {mode} = {bond}, broken bonds with a bond type of zero are also
counted. The :doc:`bond_style quartic <bond_quartic>` and :doc:`BPM
bond styles <Howto_bpm>` break bonds by doing this. See the :doc:`
Howto broken bonds <Howto_broken_bonds>` doc page for more details.
Note that the group setting is ignored for broken bonds; all broken
bonds in the system are counted.
If the {mode} setting is {angle} then the count of angles for each
angle type is tallied. Only angles with all 3 atoms in the specified
group are counted.
If the {mode} setting is {dihedral} then the count of dihedrals for
each dihedral type is tallied. Only dihedrals with all 4 atoms in the
specified group are counted.
If the {mode} setting is {improper} then the count of impropers for
each improper type is tallied. Only impropers with all 4 atoms in the
specified group are counted.
----------
Output info
"""""""""""
This compute calculates a global vector of counts. If the mode is
{atom} or {bond} or {angle} or {dihedral} or {improper}, then the
vector length is the number of atom types or bond types or angle types
or dihedral types or improper types, respectively.
If the mode is {bond} this compute also calculates a global scalar
which is the number of broken bonds with type = 0, as explained above.
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 scalar and vector values calculated by this compute are "extensive".
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
none
Default
"""""""
none

2
doc/src/compute_dipole.rst
View File

@ -42,7 +42,7 @@ geometric center times the net charge from the computed dipole
vector. Both per-atom charges and per-atom dipole moments, if present,
contribute to the computed dipole.
.. versionadded:: TBD
.. versionadded:: 28Mar2023
Compute *dipole/tip4p* includes adjustments for the charge carrying
point M in molecules with TIP4P water geometry. The corresponding

2
doc/src/compute_dipole_chunk.rst
View File

@ -51,7 +51,7 @@ center times the net charge from the computed dipole vector. Both
per-atom charges and per-atom dipole moments, if present, contribute to
the computed dipole.
.. versionadded:: TBD
.. versionadded:: 28Mar2023
Compute *dipole/tip4p/chunk* includes adjustments for the charge
carrying point M in molecules with TIP4P water geometry. The

10
doc/src/compute_erotate_sphere.rst
View File

@ -1,8 +1,12 @@
.. index:: compute erotate/sphere
.. index:: compute erotate/sphere/kk
compute erotate/sphere command
==============================
Accelerator Variants: *erotate/sphere/kk*
Syntax
""""""
@ -36,6 +40,12 @@ is the particle's angular velocity.
spheres, not disks, meaning their moment of inertia will be the same
as in 3d.
----------
.. include:: accel_styles.rst
----------
Output info
"""""""""""

2
doc/src/compute_pressure_alchemy.rst
View File

@ -26,7 +26,7 @@ Examples
Description
"""""""""""
.. versionadded:: TBD
.. versionadded:: 28Mar2023
Define a compute style that makes the "mixed" system pressure available
for a system that uses the :doc:`fix alchemy <fix_alchemy>` command to

4
doc/src/compute_ptm_atom.rst
View File

@ -66,8 +66,8 @@ The deviation is calculated as:
\text{RMSD}(\mathbf{u}, \mathbf{v})
= \min_{s, \mathbf{Q}} \sqrt{\frac{1}{N} \sum\limits_{i=1}^{N}
{\left\lVert s[\vec{u_i} - \mathbf{\bar{u}}]
- \mathbf{Q} \cdot \vec{v_i} \right\rVert}^2}
{\left\lVert s[\vec{u}_i - \mathbf{\bar{u}}]
- \mathbf{Q} \cdot \vec{v}_i \right\rVert}^2}
Here, :math:`\vec u` and :math:`\vec v` contain the coordinates of the local
and ideal structures respectively, :math:`s` is a scale factor, and

15
doc/src/compute_reduce.rst
View File

@ -23,7 +23,7 @@ Syntax
*reduce/region* arg = region-ID
region-ID = ID of region to use for choosing atoms
* mode = *sum* or *min* or *max* or *ave* or *sumsq* or *avesq* or *sumabs* or *aveabs*
* mode = *sum* or *min* or *minabs* or *max* or *maxabs* or *ave* or *sumsq* or *avesq* or *sumabs* or *aveabs*
* one or more inputs can be listed
* input = *x* or *y* or *z* or *vx* or *vy* or *vz* or *fx* or *fy* or *fz* or c_ID or c_ID[N] or f_ID or f_ID[N] or v_name
@ -71,12 +71,13 @@ vectors.
The reduction operation is specified by the *mode* setting. The *sum*
option adds the values in the vector into a global total. The *min*
or *max* options find the minimum or maximum value across all vector
values. The *ave* setting adds the vector values into a global total,
then divides by the number of values in the vector. The *sumsq*
option sums the square of the values in the vector into a global
total. The *avesq* setting does the same as *sumsq*, then divides the
sum of squares by the number of values. The last two options can be
useful for calculating the variance of some quantity (e.g., variance =
values. The *minabs* or *maxabs* options find the minimum or maximum
value across all absolute vector values. The *ave* setting adds the
vector values into a global total, then divides by the number of values
in the vector. The *sumsq* option sums the square of the values in the
vector into a global total. The *avesq* setting does the same as *sumsq*,
then divides the sum of squares by the number of values. The last two options
can be useful for calculating the variance of some quantity (e.g., variance =
sumsq :math:`-` ave\ :math:`^2`). The *sumabs* option sums the absolute
values in the vector into a global total. The *aveabs* setting does the same
as *sumabs*, then divides the sum of absolute values by the number of

5
doc/src/compute_saed.rst
View File

@ -246,8 +246,9 @@ All array values calculated by this compute are "intensive".
Restrictions
""""""""""""
This compute is part of the DIFFRACTION package. It is only
enabled if LAMMPS was built with that package. See the :doc:`Build package <Build_package>` page for more info.
This compute is part of the DIFFRACTION package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
The compute_saed command does not work for triclinic cells.

12
doc/src/compute_stress_profile.rst
View File

@ -136,12 +136,12 @@ More information on the similarities and differences can be found in
Restrictions
""""""""""""
These computes calculate the stress tensor contributions for pair
styles only (i.e., no bond, angle, dihedral, etc. contributions, and in
the presence of bonded interactions, the result will be incorrect due to
exclusions for special bonds) and requires pairwise force calculations
not available for most many-body pair styles.
Note that :math:`k`-space calculations are also excluded.
These computes calculate the stress tensor contributions for pair styles
only (i.e., no bond, angle, dihedral, etc. contributions, and in the
presence of bonded interactions, the result may be incorrect due to
exclusions for :doc:`special bonds <special_bonds>` excluding pairs of atoms
completely). It requires pairwise force calculations not available for most
many-body pair styles. Note that :math:`k`-space calculations are also excluded.
These computes are part of the EXTRA-COMPUTE package. They are only
enabled if LAMMPS was built with that package. See the :doc:`Build

22
doc/src/compute_tally.rst
View File

@ -187,16 +187,22 @@ Both the scalar and vector values calculated by this compute are
Restrictions
""""""""""""
This compute is part of the TALLY package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package <Build_package>` page for more info.
This compute is part of the TALLY package. It is only enabled if LAMMPS
was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
Not all pair styles can be evaluated in a pairwise mode as required by
this compute. For example, 3-body and other many-body potentials,
such as :doc:`Tersoff <pair_tersoff>` and
:doc:`Stillinger-Weber <pair_sw>` cannot be used. :doc:`EAM <pair_eam>`
potentials only include the pair potential portion of the EAM
interaction when used by this compute, not the embedding term. Also
bonded or Kspace interactions do not contribute to this compute.
this compute. For example, 3-body and other many-body potentials, such
as :doc:`Tersoff <pair_tersoff>` and :doc:`Stillinger-Weber <pair_sw>`
cannot be used. :doc:`EAM <pair_eam>` potentials only include the pair
potential portion of the EAM interaction when used by this compute, not
the embedding term. Also bonded or Kspace interactions do not
contribute to this compute.
These computes are not compatible with accelerated pair styles from the
GPU, INTEL, KOKKOS, or OPENMP packages. They will either create an error
or print a warning when required data was not tallied in the required way
and thus the data acquisition functions from these computes not called.
When used with dynamic groups, a :doc:`run 0 <run>` command needs to
be inserted in order to initialize the dynamic groups before accessing

2
doc/src/dump_molfile.rst
View File

@ -63,7 +63,7 @@ like element names.
The *path* keyword determines which in directories. This is a "path"
like other search paths, i.e. it can contain multiple directories
separated by a colon (or semi-colon on windows). This keyword is
separated by a colon (or semicolon on Windows). This keyword is
optional and default to ".", the current directory.
The *unwrap* option of the :doc:`dump_modify <dump_modify>` command allows

4
doc/src/fix.rst
View File

@ -256,13 +256,13 @@ accelerated styles exist.
* :doc:`langevin/drude <fix_langevin_drude>` - Langevin temperature control of Drude oscillators
* :doc:`langevin/eff <fix_langevin_eff>` - Langevin temperature control for the electron force field model
* :doc:`langevin/spin <fix_langevin_spin>` - Langevin temperature control for a spin or spin-lattice system
* :doc:`latte <fix_latte>` - wrapper on LATTE density-functional tight-binding code
* :doc:`lb/fluid <fix_lb_fluid>` - lattice-Boltzmann fluid on a uniform mesh
* :doc:`lb/momentum <fix_lb_momentum>` - :doc:`fix momentum <fix_momentum>` replacement for use with a lattice-Boltzmann fluid
* :doc:`lb/viscous <fix_lb_viscous>` - :doc:`fix viscous <fix_viscous>` replacement for use with a lattice-Boltzmann fluid
* :doc:`lineforce <fix_lineforce>` - constrain atoms to move in a line
* :doc:`manifoldforce <fix_manifoldforce>` - restrain atoms to a manifold during minimization
* :doc:`mdi/qm <fix_mdi_qm>` - LAMMPS operates as driver for a quantum code via the MolSSI Driver Interface (MDI)
* :doc:`mdi/qm <fix_mdi_qm>` - LAMMPS operates as a client for a quantum code via the MolSSI Driver Interface (MDI)
* :doc:`mdi/qmmm <fix_mdi_qmmm>` - LAMMPS operates as client for QM/MM simulation with a quantum code 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

4
doc/src/fix_adapt.rst
View File

@ -133,6 +133,8 @@ formulas for the meaning of these parameters:
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`born/coul/long, born/coul/msm <pair_born>` | coulombic_cutoff | type global |
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`born/gauss <pair_born_gauss>` | biga0,biga1,r0 | type pairs |
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`buck, buck/coul/cut <pair_buck>` | a,c | type pairs |
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`buck/coul/long, buck/coul/msm <pair_buck>` | a,c,coulombic_cutoff | type pairs |
@ -161,6 +163,8 @@ formulas for the meaning of these parameters:
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`harmonic/cut <pair_harmonic_cut>` | k, cutoff | type pairs |
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`kim <pair_kim>` | scale | type global |
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`lennard/mdf <pair_mdf>` | A,B | type pairs |
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`lj/class2 <pair_class2>` | epsilon,sigma | type pairs |

2
doc/src/fix_alchemy.rst
View File

@ -24,7 +24,7 @@ Examples
Description
"""""""""""
.. versionadded:: TBD
.. versionadded:: 28Mar2023
This fix command enables an "alchemical transformation" to be performed
between two systems, whereby one system slowly transforms into the other

3
doc/src/fix_ave_correlate_long.rst
View File

@ -15,7 +15,7 @@ Syntax
* Nevery = use input values every this many time steps
* Nfreq = save state of the time correlation functions every this many time steps
* one or more input values can be listed
* value = c_ID, c_ID[N], f_ID, f_ID[N], v_name
* value = c_ID, c_ID[N], f_ID, f_ID[N], v_name, v_name[I]
.. parsed-literal::
@ -24,6 +24,7 @@ Syntax
f_ID = global scalar calculated by a fix with ID
f_ID[I] = Ith component of global vector calculated by a fix with ID
v_name = global value calculated by an equal-style variable with name
v_name[I] = Ith component of global vector calculated by a vector-style variable with name
* zero or more keyword/arg pairs may be appended
* keyword = *type* or *start* or *file* or *overwrite* or *title1* or *title2* or *ncorr* or *nlen* or *ncount*

51
doc/src/fix_dpd_source.rst
View File

@ -18,18 +18,21 @@ Syntax
* ID, group-ID are documented in :doc:`fix <fix>` command
* edpd/source or tdpd/source = style name of this fix command
* index (only specified for tdpd/source) = index of chemical species (1 to Nspecies)
* keyword = *sphere* or *cuboid*
* keyword = *sphere* or *cuboid* or *region*
.. parsed-literal::
*sphere* values = cx,cy,cz,radius,source
*sphere* args = cx cy cz radius source
cx,cy,cz = x,y,z center of spherical domain (distance units)
radius = radius of a spherical domain (distance units)
source = heat source or concentration source (flux units, see below)
*cuboid* values = cx,cy,cz,dLx,dLy,dLz,source
cx,cy,cz = x,y,z lower left corner of a cuboid domain (distance units)
*cuboid* values = cx cy cz dLx dLy dLz source
cx,cy,cz = x,y,z center of a cuboid domain (distance units)
dLx,dLy,dLz = x,y,z side length of a cuboid domain (distance units)
source = heat source or concentration source (flux units, see below)
*region* values = region-ID source
region = ID of region for heat or concentration source
source = heat source or concentration source (flux units, see below)
Examples
""""""""
@ -40,6 +43,7 @@ Examples
fix 1 all edpd/source cuboid 0.0 0.0 0.0 20.0 10.0 10.0 -0.01
fix 1 all tdpd/source 1 sphere 5.0 0.0 0.0 5.0 0.01
fix 1 all tdpd/source 2 cuboid 0.0 0.0 0.0 20.0 10.0 10.0 0.01
fix 1 all tdpd/source 1 region lower -0.01
Description
"""""""""""
@ -57,37 +61,50 @@ heat conduction with a source term (see Fig.12 in :ref:`(Li2014) <Li2014b>`)
or diffusion with a source term (see Fig.1 in :ref:`(Li2015) <Li2015b>`), as
an analog of a periodic Poiseuille flow problem.
If the *sphere* keyword is used, the *cx,cy,cz,radius* defines a
spherical domain to apply the source flux to.
.. deprecated:: TBD
If the *cuboid* keyword is used, the *cx,cy,cz,dLx,dLy,dLz* defines a
cuboid domain to apply the source flux to.
The *sphere* and *cuboid* keywords will be removed in a future version
of LAMMPS. The same functionality and more can be achieved with a region.
If the *sphere* keyword is used, the *cx, cy, cz, radius* values define
a spherical domain to apply the source flux to.
If the *cuboid* keyword is used, the *cx, cy, cz, dLx, dLy, dLz* define
a cuboid domain to apply the source flux to.
If the *region* keyword is used, the *region-ID* selects which
:doc:`region <region>` to apply the source flux to.
----------
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
No information about this fix is written to :doc:`binary restart files <restart>`. None of the :doc:`fix_modify <fix_modify>` options
are relevant to this fix. No global or per-atom quantities are stored
by this fix for access by various :doc:`output commands <Howto_output>`.
No parameter of this fix can be used with the *start/stop* keywords of
the :doc:`run <run>` command. This fix is not invoked during :doc:`energy minimization <minimize>`.
No information of these fixes is written to :doc:`binary restart files
<restart>`. None of the :doc:`fix_modify <fix_modify>` options are
relevant to these fixes. No global or per-atom quantities are stored by
these fixes for access by various :doc:`output commands <Howto_output>`.
No parameter of these fixes can be used with the *start/stop* keywords
of the :doc:`run <run>` command. These fixes are not invoked during
:doc:`energy minimization <minimize>`.
Restrictions
""""""""""""
This fix is part of the DPD-MESO package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package <Build_package>` page for more info.
These fixes are part of the DPD-MESO package. They are only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
Fix *edpd/source* must be used with the :doc:`pair_style edpd <pair_mesodpd>` command. Fix *tdpd/source* must be used with the
Fix *edpd/source* must be used with the :doc:`pair_style edpd
<pair_mesodpd>` command. Fix *tdpd/source* must be used with the
:doc:`pair_style tdpd <pair_mesodpd>` command.
Related commands
""""""""""""""""
:doc:`pair_style edpd <pair_mesodpd>`, :doc:`pair_style tdpd <pair_mesodpd>`,
:doc:`compute edpd/temp/atom <compute_edpd_temp_atom>`, :doc:`compute tdpd/cc/atom <compute_tdpd_cc_atom>`
:doc:`compute edpd/temp/atom <compute_edpd_temp_atom>`,
:doc:`compute tdpd/cc/atom <compute_tdpd_cc_atom>`
Default
"""""""

2
doc/src/fix_efield.rst
View File

@ -45,7 +45,7 @@ external electric field being applied to the system. If the system
contains point-dipoles, also add a torque on the dipoles due to the
external electric field.
.. versionadded:: TBD
.. versionadded:: 28Mar2023
When the *efield/tip4p* style is used, the E-field will be applied to
the position of the virtual charge site M of a TIP4P molecule instead of

2
doc/src/fix_indent.rst
View File

@ -19,7 +19,7 @@ Syntax
.. parsed-literal::
*sphere* args = x y z R
x,y,z = initial position of center of indenter (distance units)
x,y,z = position of center of indenter (distance units)
R = sphere radius of indenter (distance units)
any of x,y,z,R can be a variable (see below)
*cylinder* args = dim c1 c2 R

269
doc/src/fix_latte.rst
View File

@ -1,269 +0,0 @@
.. index:: fix latte
fix latte command
=================
Syntax
""""""
.. parsed-literal::
fix ID group-ID latte keyword value ...
* ID, group-ID are documented in :doc:`fix <fix>` command
* latte = style name of this fix command
* zero or more keyword/value pairs may be appended
.. parsed-literal::
keyword = *coulomb* or *exclude*
*coulomb* value = peID
peID = ID of compute used to calculate per-atom energy
*exclude* value = fixID
fixID = ID of fix which potentially excludes atoms before calling LATTE
Examples
""""""""
.. code-block:: LAMMPS
fix dftb all latte
fix dftb all exclude GCMC
Description
"""""""""""
This fix style is a wrapper on the self-consistent charge transfer
density functional based tight binding (DFTB) code LATTE. If you
download and build LATTE, it can be called as a library by LAMMPS via
this fix to run dynamics or perform energy minimization using DFTB
forces and energies computed by LATTE.
LATTE is principally developed and supported by Marc Cawkwell and
co-workers at Los Alamos National Laboratory (LANL). See the full
list of contributors in the src/LATTE/README file.
To use this fix, the LATTE program needs to be compiled as a library
and linked with LAMMPS. LATTE can be downloaded (or cloned) from
`https://github.com/lanl/LATTE <https://github.com/lanl/LATTE>`_.
Instructions on how to download and build LATTE on your system can be
found in the lib/latte/README. Note that you can also use the "make
lib-latte" command from the LAMMPS src directory to automate this
process.
Once LAMMPS is built with the LATTE package, you can run the example
input scripts for molecular dynamics or energy minimization that are
found in examples/latte.
A step-by-step tutorial can be followed at: `LAMMPS-LATTE tutorial <https://github.com/lanl/LATTE/wiki/Using-LATTE-through-LAMMPS>`_
Currently, LAMMPS must be run in serial or as a single MPI task, to
use this fix. This is because the version of the LATTE library LAMMPS
uses does not support MPI. On the LAMMPS size, this is typically not
a bottleneck, since LATTE will be doing 99% or more of the work to
compute quantum-accurate forces. On the LATTE side, the LATTE library
does support threaded parallelism via OpenMP. You must build the
LATTE library with OpenMP support, then set the OMP_NUM_THREADS
environment variable before performing a LAMMPS + LATTE simulation to
tell LATTE how many threads to invoke.
.. note::
NEB calculations can be done using this fix using multiple
replicas and running LAMMPS in parallel. However, each replica must
be run on a single MPI task. For details, see the :doc:`neb <neb>`
command page and the :doc:`-partition command-line switch <Run_options>`
----------
The *coulomb* argument is not yet supported by fix latte (as of Sept
2022). Eventually it will be used to enable LAMMPS to calculate a
Coulomb potential as an alternative to LATTE performing the
calculation.
.. versionadded:: 15Sep2022
The *exclude* argument allows this fix to work in tandem with another
fix which may decide to delete one or more atoms of molecules. The
specified fixID is the ID of the other fix.
The one current example of such a fix is the :doc:`fix gcmc
<fix_gcmc>` command which performs Monte Carlo insertions and
deletions. If a trial deletion is performed, then LAMMPS needs to
only pass LATTE the atoms which remain. Fix gcmc does not actually
remove any atoms until after the new energy is computed (in this case
by LATTE), and a Monte Carlo accept/reject decision is made for the
trial deletion.
----------
LATTE is a code for performing self-consistent charge transfer
tight-binding (SC-TB) calculations of total energies and the forces
acting on atoms in molecules and solids. This tight-binding method is
becoming more and more popular and widely used in chemistry,
biochemistry, material science, etc.
The SC-TB formalism is derived from an expansion of the Kohn-Sham
density functional to second order in charge fluctuations about a
reference charge of overlapping atom-centered densities and bond
integrals are parameterized using a Slater-Koster tight-binding
approach. This procedure, which usually is referred to as the DFTB
method has been described in detail by (:ref:`Elstner <Elstner>`) and
(:ref:`Finnis <Finnis2>`) and coworkers.
The work of the LATTE developers follows that of Elstner closely with
respect to the physical model. However, the development of LATTE is
geared principally toward large-scale, long duration, microcanonical
quantum-based Born-Oppenheimer molecular dynamics (QMD) simulations.
One of the main bottlenecks of an electronic structure calculation is
the solution of the generalized eigenvalue problem which scales with
the cube of the system size O(N\^3).
The Theoretical and Computer sciences divisions at Los Alamos National
Laboratory have accumulated large experience addressing this issue by
calculating the density matrix directly instead of using
diagonalization. We typically use a recursive sparse Fermi-operator
expansion using second-order spectral projection functions
(SP2-algorithm), which was introduced by Niklasson in 2002
(:ref:`Niklasson2002 <Niklasson2002>`), (:ref:`Rubensson <Rubensson>`),
(:ref:`Mniszewski <Mniszewski>`). When the matrices involved in the
recursive expansion are sufficiently sparse, the calculation of the
density matrix scales linearly as a function of the system size O(N).
Another important feature is the extended Lagrangian framework for
Born-Oppenheimer molecular dynamics (XL-BOMD)
(:ref:`Niklasson2008 <Niklasson2008>`) (:ref:`Niklasson2014 <Niklasson2014>`),
(:ref:`Niklasson2017 <Niklasson2017>`) that allows for a drastic reduction
or even a complete removal of the iterative self-consistent field
optimization. Often only a single density matrix calculation per
molecular dynamics time step is required, yet total energy stability
is well maintained. The SP2 and XL-BOMD techniques enables stable
linear scaling MD simulations with a very small computational
overhead. This opens a number of opportunities in many different
areas of chemistry and materials science, as we now can simulate
larger system sizes and longer time scales
(:ref:`Cawkwell2012 <Cawkwell2012>`), (:ref:`Negre2016 <Negre2016>`).
----------
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
No information about this fix is written to :doc:`binary restart files
<restart>`.
The :doc:`fix_modify <fix_modify>` *energy* option is supported by
this fix to add the potential energy computed by LATTE to the global
potential energy of the system as part of :doc:`thermodynamic output
<thermo_style>`. The default setting for this fix is :doc:`fix_modify
energy yes <fix_modify>`.
The :doc:`fix_modify <fix_modify>` *virial* option is supported by
this fix to add the contribution computed by LATTE to the global
pressure of the system as part of :doc:`thermodynamic output
<thermo_style>`. The default setting for this fix is :doc:`fix_modify
virial yes <fix_modify>`.
This fix computes a global scalar which can be accessed by various
:doc:`output commands <Howto_output>`. The scalar is the potential
energy discussed above. The scalar value calculated by this fix is
"extensive".
No parameter of this fix can be used with the *start/stop* keywords of
the :doc:`run <run>` command.
The DFTB forces computed by LATTE via this fix are used during an
energy minimization, invoked by the :doc:`minimize <minimize>`
command.
.. note::
If you want the potential energy associated with the DFTB
forces to be included in the total potential energy of the system (the
quantity being minimized), you MUST not disable the
:doc:`fix_modify <fix_modify>` *energy* option for this fix.
Restrictions
""""""""""""
This fix is part of the LATTE package. It is only enabled if LAMMPS
was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
You must use metal units, as set by the :doc:`units <units>` command to
use this fix.
LATTE does not currently compute per-atom energy or per-atom virial
contributions. So they will not show up as part of the calculations
performed by the :doc:`compute pe/atom <compute_pe_atom>` or
:doc:`compute stress/atom <compute_stress_atom>` commands.
Related commands
""""""""""""""""
none
Default
"""""""
none
----------
.. _Elstner:
**(Elstner)** M. Elstner, D. Poresag, G. Jungnickel, J. Elsner,
M. Haugk, T. Frauenheim, S. Suhai, and G. Seifert, Phys. Rev. B, 58,
7260 (1998).
.. _Elstner1:
**(Elstner)** M. Elstner, D. Poresag, G. Jungnickel, J. Elsner,
M. Haugk, T. Frauenheim, S. Suhai, and G. Seifert, Phys. Rev. B, 58,
7260 (1998).
.. _Finnis2:
**(Finnis)** M. W. Finnis, A. T. Paxton, M. Methfessel, and M. van
Schilfgarde, Phys. Rev. Lett., 81, 5149 (1998).
.. _Mniszewski:
**(Mniszewski)** S. M. Mniszewski, M. J. Cawkwell, M. E. Wall,
J. Mohd-Yusof, N. Bock, T. C. Germann, and A. M. N. Niklasson,
J. Chem. Theory Comput., 11, 4644 (2015).
.. _Niklasson2002:
**(Niklasson2002)** A. M. N. Niklasson, Phys. Rev. B, 66, 155115 (2002).
.. _Rubensson:
**(Rubensson)** E. H. Rubensson, A. M. N. Niklasson, SIAM
J. Sci. Comput. 36 (2), 147-170, (2014).
.. _Niklasson2008:
**(Niklasson2008)** A. M. N. Niklasson, Phys. Rev. Lett., 100, 123004
(2008).
.. _Niklasson2014:
**(Niklasson2014)** A. M. N. Niklasson and M. Cawkwell, J. Chem. Phys.,
141, 164123, (2014).
.. _Niklasson2017:
**(Niklasson2017)** A. M. N. Niklasson, J. Chem. Phys., 147, 054103 (2017).
.. _Cawkwell2012:
**(Cawkwell2012)** A. M. N. Niklasson, M. J. Cawkwell, Phys. Rev. B, 86
(17), 174308 (2012).
.. _Negre2016:
**(Negre2016)** C. F. A. Negre, S. M. Mniszewski, M. J. Cawkwell,
N. Bock, M. E. Wall, and A. M. N. Niklasson, J. Chem. Theory Comp.,
12, 3063 (2016).

138
doc/src/fix_mdi_qm.rst
View File

@ -8,12 +8,12 @@ Syntax
.. parsed-literal::
fix ID group-ID mdi/qm keyword
fix ID group-ID mdi/qm keyword value(s) keyword value(s) ...
* ID, group-ID are documented in :doc:`fix <fix>` command
* mdi/qm = style name of this fix command
* zero or more keyword/value pairs may be appended
* keyword = *virial* or *add* or *every* or *connect* or *elements*
* keyword = *virial* or *add* or *every* or *connect* or *elements* or *mc*
.. parsed-literal::
@ -29,7 +29,9 @@ Syntax
yes = perform a one-time connection to the MDI engine code
no = do not perform the connection operation
*elements* args = N_1 N_2 ... N_ntypes
N_1,N_2,...N_ntypes = atomic number for each of ntypes LAMMPS atom types
N_1,N_2,...N_ntypes = chemical symbol for each of ntypes LAMMPS atom types
*mc* args = mcfixID
mcfixID = ID of a Monte Carlo fix designed to work with this fix
Examples
""""""""
@ -38,7 +40,7 @@ Examples
fix 1 all mdi/qm
fix 1 all mdi/qm virial yes
fix 1 all mdi/qm add no every 100 elements 13 29
fix 1 all mdi/qm add no every 100 elements C C H O
Description
"""""""""""
@ -57,12 +59,27 @@ The server code must support use of the `MDI Library
<https://molssi-mdi.github.io/MDI_Library/html/index.html>`_ as
explained below.
Typically, to use this fix, the input script should not define any
other classical force field components, e.g. a pair style, bond style,
etc.
These are example use cases for this fix, discussed further below:
* perform an ab initio MD (AIMD) simulation with quantum forces
* perform an energy minimization with quantum forces
* perform a nudged elastic band (NEB) calculation with quantum forces
* perform a QM calculation for a series of independent systems which LAMMPS reads or generates
* perform a QM calculation for a series of independent systems which
LAMMPS reads or generates once
* run a classical MD simulation and calculate QM energy/forces once
every N steps on the current configuration
More generally any command which calculates per-atom forces can instead
use quantum forces by defining this fix. Examples are the Monte Carlo
commands :doc:`fix gcmc <fix_gcmc>` and :doc:`fix atom/swap
<fix_atom_swap>`, as well as the :doc:`compute born/matrix
<compute_born_matrix>` command. The only requirement is that internally
the command invokes the post_force() method of fixes such as this one,
which will trigger the quantum calculation.
The code coupling performed by this command is done via the `MDI
Library <https://molssi-mdi.github.io/MDI_Library/html/index.html>`_.
@ -72,27 +89,32 @@ for MDI. See the :doc:`Howto mdi <Howto_mdi>` page for more
information about how LAMMPS can operate as either an MDI driver or
engine.
The examples/mdi directory contains input scripts using this fix in
The ``examples/mdi`` directory contains input scripts using this fix in
the various use cases discussed below. In each case, two instances of
LAMMPS are used, once as an MDI driver, once as an MDI engine
(surrogate for a QM code). The examples/mdi/README file explains how
to launch two codes so that they communicate via the MDI library using
either MPI or sockets. Any QM code that supports MDI could be used in
place of LAMMPS acting as a QM surrogate. See the :doc:`Howto mdi
<Howto_mdi>` page for a current list (March 2022) of such QM codes.
LAMMPS are used, once as an MDI driver, once as an MDI engine (surrogate
for a QM code). The ``examples/mdi/README`` file explains how to launch
two codes so that they communicate via the MDI library using either MPI
or sockets. Any QM code that supports MDI could be used in place of
LAMMPS acting as a QM surrogate. See the :doc:`Howto mdi <Howto_mdi>`
page for a current list (March 2022) of such QM codes. The
``examples/QUANTUM`` directory has examples for coupling LAMMPS to 3 QM
codes either via this fix or the :doc:`fix mdi/qmmm <fix_mdi_qmmm>`
command.
Note that an engine code can support MDI in either or both of two
modes. It can be used as a stand-alone code, launched at the same
time as LAMMPS. Or it can be used as a plugin library, which LAMMPS
loads. See the :doc:`mdi plugin <mdi>` command for how to trigger
LAMMPS to load a plugin library. The examples/mdi/README file
explains how to launch the two codes in either mode.
Note that an engine code can support MDI in either or both of two modes.
It can be used as a stand-alone code, launched at the same time as
LAMMPS. Or it can be used as a plugin library, which LAMMPS loads. See
the :doc:`mdi plugin <mdi>` command for how to trigger LAMMPS to load a
plugin library. The ``examples/mdi/README`` file and
``examples/QUANTUM/QM-code/README`` files explain how to launch the two
codes in either mode.
----------
The *virial* keyword setting of yes or no determines whether
LAMMPS will request the QM code to also compute and return
a 6-element symmetric virial tensor for the system.
The *virial* keyword setting of yes or no determines whether LAMMPS
will request the QM code to also compute and return the QM
contribution to a stress tensor for the system which LAMMPS will
convert to a 6-element symmetric virial tensor.
The *add* keyword setting of *yes* or *no* determines whether the
energy and forces and virial returned by the QM code will be added to
@ -109,25 +131,27 @@ commands. See details below.
The *every* keyword determines how often the QM code will be invoked
during a dynamics run with the current LAMMPS simulation box and
configuration of atoms. The QM code will be called once every
*Nevery* timesteps.
*Nevery* timesteps. By default *Nevery* = 1.
The *connect* keyword determines whether this fix performs a one-time
connection to the QM code. The default is *yes*. The only time a
*no* is needed is if this command is used multiple times in an input
script. E.g. if it used inside a loop which also uses the :doc:`clear
<clear>` command to destroy the system (including any defined fixes).
See the examples/mdi/in.series.driver script as an example of this,
where LAMMPS is using the QM code to compute energy and forces for a
series of system configurations. In this use case *connect no*
is used along with the :doc:`mdi connect and exit <mdi>` command
to one-time initiate/terminate the connection outside the loop.
connection to the QM code. The default is *yes*. The only time a *no*
is needed is if this command is used multiple times in an input script
and the MDI coupling is between two stand-alone codes (not plugin mode).
E.g. if it used inside a loop which also uses the :doc:`clear <clear>`
command to destroy the system (including this fix). See the
``examples/mdi/in.series.driver`` script as an example of this, where
LAMMPS is using the QM code to compute energy and forces for a series of
system configurations. In this use case *connect no* is used along with
the :doc:`mdi connect and exit <mdi>` command to one-time
initiate/terminate the connection outside the loop.
The *elements* keyword allows specification of what element each
LAMMPS atom type corresponds to. This is specified by the atomic
number of the element, e.g. 13 for Al. An atomic number must be
specified for each of the ntypes LAMMPS atom types. Ntypes is
typically specified via the create_box command or in the data file
read by the read_data command.
LAMMPS atom type corresponds to. This is specified by the chemical
symbol of the element, e.g. C or Al or Si. A symbol must be specified
for each of the ntypes LAMMPS atom types. Multiple LAMMPS types can
represent the same element. Ntypes is typically specified via the
:doc:`create_box <create_box>` command or in the data file read by the
:doc:`read_data <read_data>` command.
If this keyword is specified, then this fix will send the MDI
">ELEMENTS" command to the engine, to ensure the two codes are
@ -136,10 +160,18 @@ not specified, then this fix will send the MDI >TYPES command to the
engine. This is fine if both the LAMMPS driver and the MDI engine are
initialized so that the atom type values are consistent in both codes.
The *mc* keyword enables this fix to be used with a Monte Carlo (MC)
fix to calculate before/after quantum energies as part of the MC
accept/reject criterion. The :doc:`fix gcmc <fix_gcmc>` and :doc:`fix
atom/swap <fix_atom_swap>` commands can be used in this manner.
Specify the ID of the MC fix following the *mc* keyword. This allows
the two fixes to coordinate when MC events are being calculated versus
MD timesteps between the MC events.
----------
The following 3 example use cases are illustrated in the examples/mdi
directory. See its README file for more details.
The following 3 example use cases are illustrated in the
``examples/mdi`` directory. See its README file for more details.
(1) To run an ab initio MD (AIMD) dynamics simulation, or an energy
minimization with QM forces, or a multi-replica NEB calculation, use
@ -248,29 +280,31 @@ invoked by the :doc:`minimize <minimize>` command.
Restrictions
""""""""""""
This command is part of the MDI package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
This fix is part of the MDI package. It is only enabled if LAMMPS
was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
The QM code does not currently compute and return per-atom energy or
per-atom virial contributions. So they will not show up as part of
the calculations performed by the :doc:`compute pe/atom
<compute_pe_atom>` or :doc:`compute stress/atom <compute_stress_atom>`
commands.
To use LAMMPS as an MDI driver in conjunction with other MDI-enabled
codes (MD or QM codes), the :doc:`units <units>` command should be
used to specify *real* or *metal* units. This will ensure the correct
unit conversions between LAMMPS and MDI units. The other code will
also perform similar unit conversions into its preferred units.
codes (MD or QM codes), the :doc:`units <units>` command should be used
to specify *real* or *metal* units. This will ensure the correct unit
conversions between LAMMPS and MDI units. The other code will also
perform similar unit conversions into its preferred units.
LAMMPS can also be used as an MDI driver in other unit choices it
supports, e.g. *lj*, but then no unit conversion is performed.
supports, e.g. *lj*, but then no unit conversion to MDI units is
performed.
If this fix is used in conjunction with a QM code that does not support
periodic boundary conditions (more specifically, a QM code that does not
support the ``>CELL`` MDI command), the LAMMPS system must be fully
non-periodic. I.e. no dimension of the system can be periodic.
Related commands
""""""""""""""""
:doc:`mdi plugin <mdi>`, :doc:`mdi engine <mdi>`
:doc:`mdi plugin <mdi>`,
:doc:`mdi engine <mdi>`,
:doc:`fix mdi/qmmm <fix_mdi_qmmm>`
Default
"""""""

279
doc/src/fix_mdi_qmmm.rst Normal file
View File

@ -0,0 +1,279 @@
.. index:: fix mdi/qmmm
fix mdi/qmmm command
====================
Syntax
""""""
.. parsed-literal::
fix ID group-ID mdi/qmmm mode keyword value(s) keyword value(s) ...
* ID, group-ID are documented in :doc:`fix <fix>` command
* mdi/qmmm = style name of this fix command
* mode = *direct* or *potential*
* zero or more keyword/value pairs may be appended
* keyword = *virial* or *add* or *every* or *connect* or *elements*
.. parsed-literal::
*virial* args = *yes* or *no*
yes = request virial tensor from server code
no = do not request virial tensor from server code
*connect* args = *yes* or *no*
yes = perform a one-time connection to the MDI engine code
no = do not perform the connection operation
*elements* args = N_1 N_2 ... N_ntypes
N_1,N_2,...N_ntypes = chemical symbol for each of ntypes LAMMPS atom types
Examples
""""""""
.. code-block:: LAMMPS
fix 1 all mdi/qmmm direct
fix 1 all mdi/qmmm potential virial yes
fix 1 all mdi/qmmm potential virial yes elements 13 29
Description
"""""""""""
.. versionadded:: 28Mar2023
This command enables LAMMPS to act as a client with another server code
to perform a coupled QM/MM (quantum-mechanics/molecular-mechanics)
simulation. LAMMPS will perform classical MD (molecular mechanics
or MM) for the (typically larger) MM portion of the system. A quantum
mechanics code will calculate quantum energy and forces for the QM
portion of the system. The two codes work together to calculate the
energy and forces due to the cross interactions between QM and MM atoms.
The QM server code must support use of the `MDI Library
<https://molssi-mdi.github.io/MDI_Library/html/index.html>`_ as
explained below.
The partitioning of the system between QM and MM atoms is as follows.
Atoms in the specified group are QM atoms; the remaining atoms are MM
atoms. The input script should thus define this partitioning.
See additional information below about other requirements for an input
script to use this fix and perform a QM/MM simulation.
The code coupling performed by this command is done via the `MDI
Library <https://molssi-mdi.github.io/MDI_Library/html/index.html>`_.
LAMMPS runs as an MDI driver (client), and sends MDI commands to an
external MDI engine code (server), in this case a QM code which has
support for MDI. See the :doc:`Howto mdi <Howto_mdi>` page for more
information about how LAMMPS can operate as either an MDI driver or
engine.
The ``examples/QUANTUM`` directory has sub-directories with example
input scripts using this fix in tandem with different QM codes. The
README files in the sub-directories explain how to download and build
the various QM codes. They also explain how to launch LAMMPS and the QM
code so that they communicate via the MDI library using either MPI or
sockets. Any QM code that supports MDI could be used in addition to
those discussed in the sub-directories. See the :doc:`Howto mdi
<Howto_mdi>` page for a current list (March 2022) of such QM codes.
Note that an engine code can support MDI in either or both of two modes.
It can be used as a stand-alone code, launched at the same time as
LAMMPS. Or it can be used as a plugin library, which LAMMPS loads. See
the :doc:`mdi plugin <mdi>` command for how to trigger LAMMPS to load a
plugin library. The ``examples/QUANTUM`` sub-directory README files
explains how to launch the two codes in either mode.
----------
The *mode* setting determines which QM/MM coupling algorithm is used.
LAMMPS currently supports *direct* and *potential* algorithms, based
on the *mode* setting. Both algorithms should give reasonably
accurate results, but some QM codes support only one of the two modes.
E.g. in the ``examples/QUANTUM`` directory, PySCF supports only *direct*,
NWChem supports only *potential*, and LATTE currently supports
neither, so it cannot be used for QM/MM simulations using this fix.
The *direct* option passes the coordinates and charges of each MM atom
to the quantum code, in addition to the coordinates of each QM atom.
The quantum code returns forces on each QM atom as well as forces on
each MM atom. The latter is effectively the force on MM atoms due to
the QM atoms.
The input script for performing a *direct* mode QM/MM simulation should
do the following:
* delete all bonds (angles, dihedrals, etc) between QM atoms
* set the charge on each QM atom to zero
* define no bonds (angles, dihedrals, etc) which involve both QM and MM atoms
* define a force field (pair, bonds, angles, optional kspace) for the entire system
The first two bullet can be performed using the :doc:`delete_bonds
<delete_bonds>` and :doc:`set <set>` commands.
The third bullet is required to have a consistent model, but is not
checked by LAMMPS.
The fourth bullet implies that non-bonded non-Coulombic interactions
(e.g. van der Waals) between QM/QM and QM/MM pairs of atoms are
computed by LAMMPS.
See the ``examples/QUANTUM/PySCF/in.*`` files for examples of input
scripts for QM/MM simulations using the *direct* mode.
The *potential* option passes the coordinates of each QM atom and a
Coulomb potential for each QM atom to the quantum code. The latter is
calculated by performing a Coulombics-only calculation for the entire
system, subtracting all QM/QM pairwise Coulombic terms, and dividing
the Coulomb energy on each QM atom by the charge of the QM atom. The
potential value represents the Coulombic influence of all the MM atoms
on each QM atom.
The quantum code returns forces and charge on each QM atom. The new
charges on the QM atom are used to re-calculate the MM force field,
resulting in altered forces on the MM atoms.
The input script for performing a *potential* mode QM/MM simulation
should do the following:
* delete all bonds (angles, dihedrals, etc) between QM atoms
* define a hybrid pair style which includes a Coulomb-only pair sub-style
* define no bonds (angles, dihedrals, etc) which involve both QM and MM atoms
* define a force field (pair, bonds, angles, optional kspace) for the entire system
The first operation can be performed using the :doc:`delete_bonds
<delete_bonds>` command. See the ``examples/QUANTUM/NWChem/in.*`` files
for examples of how to do this.
The second operation is necessary so that this fix can calculate the
Coulomb potential for the QM atoms.
The third bullet is required to have a consistent model, but is not
checked by LAMMPS.
The fourth bullet implies that non-bonded non-Coulombic interactions
(e.g. van der Waals) between QM/QM and QM/MM pairs of atoms are computed
by LAMMPS. However, some QM codes do not want the MM code (LAMMPS) to
compute QM/QM van der Waals interactions. NWChem is an example. In
this case, the coefficients for those interactions need to be turned
off, which typically requires the atom types for the QM atoms be
different than those for the MM atoms.
See the ``examples/QUANTUM/NWChem/in.*`` files for examples of input
scripts for QM/MM simulations using the *potential* mode. Those scripts
also illustrate how to turn off QM/QM van der Waals interactions.
----------
The *virial* keyword setting of yes or no determines whether LAMMPS
will request the QM code to also compute and return the QM
contribution to a stress tensor for the system which LAMMPS will
convert to a 6-element symmetric virial tensor.
The *connect* keyword determines whether this fix performs a one-time
connection to the QM code. The default is *yes*. The only time a
*no* is needed is if this command is used multiple times in an input
script. E.g. if it used inside a loop which also uses the :doc:`clear
<clear>` command to destroy the system (including this fix). As
example would be a script which loop over a series of independent QM/MM
simulations, e.g. each with their own data file. In this use case
*connect no* could be used along with the :doc:`mdi connect and exit
<mdi>` command to one-time initiate/terminate the connection outside
the loop.
The *elements* keyword allows specification of what element each
LAMMPS atom type corresponds to. This is specified by the chemical
symbol of the element, e.g. C or Al or Si. A symbol must be specified
for each of the ntypes LAMMPS atom types. Multiple LAMMPS types can
represent the same element. Ntypes is typically specified via the
:doc:`create_box <create_box>` command or in the data file read by the
:doc:`read_data <read_data>` command.
If this keyword is specified, then this fix will send the MDI
">ELEMENTS" command to the engine, to insure the two codes are
consistent in their definition of atomic species. If this keyword is
not specified, then this fix will send the MDI >TYPES command to the
engine. This is fine if both the LAMMPS driver and the MDI engine are
initialized so that the atom type values are consistent in both codes.
----------
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
No information about this fix is written to :doc:`binary restart files
<restart>`.
The :doc:`fix_modify <fix_modify>` *energy* option is supported by
this fix to add the potential energy computed by the QM code to the
global potential energy of the system as part of :doc:`thermodynamic
output <thermo_style>`. The default setting for this fix is
:doc:`fix_modify energy yes <fix_modify>`.
The :doc:`fix_modify <fix_modify>` *virial* option is supported by
this fix to add the contribution computed by the QM code to the global
pressure of the system as part of :doc:`thermodynamic output
<thermo_style>`. The default setting for this fix is :doc:`fix_modify
virial yes <fix_modify>`.
This fix computes a global scalar which can be accessed by various
:doc:`output commands <Howto_output>`. The scalar is the energy
returned by the QM code. The scalar value calculated by this fix is
"extensive".
This fix also computes a global vector with of length 6 which contains
the symmetric virial tensor values returned by the QM code. It can
likewise be accessed by various :doc:`output commands <Howto_output>`.
The ordering of values in the symmetric virial tensor is as follows:
vxx, vyy, vzz, vxy, vxz, vyz. The values will be in pressure
:doc:`units <units>`.
This fix also computes a peratom array with 3 columns which contains
the peratom forces returned by the QM code. It can likewise be
accessed by various :doc:`output commands <Howto_output>`. Note that
for *direct* mode this will be quantum forces on both QM and MM atoms.
For *potential* mode it will only be quantum forces on QM atoms; the
forces for MM atoms will be zero.
No parameter of this fix can be used with the *start/stop* keywords of
the :doc:`run <run>` command.
The forces computed by the QM code are used during an energy
minimization, invoked by the :doc:`minimize <minimize>` command.
.. note::
If you want the potential energy associated with the QM forces to
be included in the total potential energy of the system (the
quantity being minimized), you MUST not disable the
:doc:`fix_modify <fix_modify>` *energy* option for this fix.
Restrictions
""""""""""""
This command is part of the MDI package. It is only enabled if LAMMPS
was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
To use LAMMPS as an MDI driver in conjunction with other MDI-enabled
codes (MD or QM codes), the :doc:`units <units>` command should be used
to specify *real* or *metal* units. This will ensure the correct unit
conversions between LAMMPS and MDI units. The other code will also
perform similar unit conversions into its preferred units.
If this fix is used in conjunction with a QM code that does not support
periodic boundary conditions (more specifically, a QM code that does not
support the ``>CELL`` MDI command), the LAMMPS system must be fully
non-periodic. I.e. no dimension of the system can be periodic.
Related commands
""""""""""""""""
:doc:`mdi plugin <mdi>`,
:doc:`mdi engine <mdi>`,
:doc:`fix mdi/qm <fix_mdi_qm>`
Default
"""""""
The default for the optional keywords are virial = no and connect = yes.

2
doc/src/fix_pimd.rst
View File

@ -65,7 +65,7 @@ Examples
Description
"""""""""""
.. versionchanged:: TBD
.. versionchanged:: 28Mar2023
Fix pimd was renamed to fix *pimd/nvt* and fix *pimd/langevin* was added.

18
doc/src/fix_precession_spin.rst
View File

@ -103,15 +103,15 @@ possible easy axis for the magnetic spins in the defined group:
H_{cubic} = -\sum_{{ i}=1}^{N} K_{1}
\Big[
\left(\vec{s}_{i} \cdot \vec{n_1} \right)^2
\left(\vec{s}_{i} \cdot \vec{n_2} \right)^2 +
\left(\vec{s}_{i} \cdot \vec{n_2} \right)^2
\left(\vec{s}_{i} \cdot \vec{n_3} \right)^2 +
\left(\vec{s}_{i} \cdot \vec{n_1} \right)^2
\left(\vec{s}_{i} \cdot \vec{n_3} \right)^2 \Big]
+K_{2}^{(c)} \left(\vec{s}_{i} \cdot \vec{n_1} \right)^2
\left(\vec{s}_{i} \cdot \vec{n_2} \right)^2
\left(\vec{s}_{i} \cdot \vec{n_3} \right)^2
\left(\vec{s}_{i} \cdot \vec{n}_1 \right)^2
\left(\vec{s}_{i} \cdot \vec{n}_2 \right)^2 +
\left(\vec{s}_{i} \cdot \vec{n}_2 \right)^2
\left(\vec{s}_{i} \cdot \vec{n}_3 \right)^2 +
\left(\vec{s}_{i} \cdot \vec{n}_1 \right)^2
\left(\vec{s}_{i} \cdot \vec{n}_3 \right)^2 \Big]
+K_{2}^{(c)} \left(\vec{s}_{i} \cdot \vec{n}_1 \right)^2
\left(\vec{s}_{i} \cdot \vec{n}_2 \right)^2
\left(\vec{s}_{i} \cdot \vec{n}_3 \right)^2
with :math:`K_1` and :math:`K_{2c}` (in eV) the intensity coefficients
and :math:`\vec{n}_1`, :math:`\vec{n}_2` and :math:`\vec{n}_3`

2
doc/src/fix_press_berendsen.rst
View File

@ -61,7 +61,7 @@ unchanged and controlling the pressure of a surrounding fluid.
atoms. This fix can be used in conjunction with thermostatting fixes
to control the temperature, such as :doc:`fix nvt <fix_nh>` or :doc:`fix langevin <fix_langevin>` or :doc:`fix temp/berendsen <fix_temp_berendsen>`.
See the :doc:`Howto baroostat <Howto_barostat>` page for a
See the :doc:`Howto barostat <Howto_barostat>` page for a
discussion of different ways to perform barostatting.
----------

23
doc/src/fix_print.rst
View File

@ -44,6 +44,20 @@ one word. If it contains variables it must be enclosed in double
quotes to ensure they are not evaluated when the input script line is
read, but will instead be evaluated each time the string is printed.
.. versionadded:: TBD
support for vector style variables
See the :doc:`variable <variable>` command for a description of
*equal* and *vector* style variables which are typically the most
useful ones to use with the print command. Equal- and vector-style
variables can calculate formulas involving mathematical operations,
atom properties, group properties, thermodynamic properties, global
values calculated by a :doc:`compute <compute>` or :doc:`fix <fix>`,
or references to other :doc:`variables <variable>`. Vector-style
variables are printed in a bracketed, comma-separated format,
e.g. [1,2,3,4] or [12.5,2,4.6,10.1].
.. note::
As discussed on the :doc:`Commands parse <Commands_parse>` doc
@ -77,15 +91,6 @@ timesteps 10,20,30,100,200,300,1000,2000,etc:
The specified group-ID is ignored by this fix.
See the :doc:`variable <variable>` command for a description of
*equal* style variables which are the most useful ones to use with the
fix print command, since they are evaluated afresh each timestep that
the fix print line is output. Equal-style variables calculate
formulas involving mathematical operations, atom properties, group
properties, thermodynamic properties, global values calculated by a
:doc:`compute <compute>` or :doc:`fix <fix>`, or references to other
:doc:`variables <variable>`.
If the *file* or *append* keyword is used, a filename is specified to
which the output generated by this fix will be written. If *file* is
used, then the filename is overwritten if it already exists. If

3
doc/src/fix_reaxff_species.rst
View File

@ -148,7 +148,8 @@ formulae). The *specieslist* and *masslimit* keywords cannot both be
used in the same *reaxff/species* fix. The *delete_rate_limit*
keyword can enforce an upper limit on the overall rate of molecule
deletion. The number of deletion occurrences is limited to Nlimit
within an interval of Nsteps timesteps. When using the
within an interval of Nsteps timesteps. Nlimit can be specified with
an equal-style :doc:`variable <variable>`. When using the
*delete_rate_limit* keyword, no deletions are permitted to occur
within the first Nsteps timesteps of the first run (after reading a
either a data or restart file).

12
doc/src/fix_saed_vtk.rst
View File

@ -163,11 +163,17 @@ intensity outputs.
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
No information about this fix is written to :doc:`binary restart files <restart>`. None of the :doc:`fix_modify <fix_modify>` options
are relevant to this fix.
This fix is part of the DIFFRACTION package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
No information about this fix is written to :doc:`binary restart files
<restart>`. None of the :doc:`fix_modify <fix_modify>` options are
relevant to this fix.
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
""""""""""""

6
doc/src/fix_wall.rst
View File

@ -194,7 +194,7 @@ For style *wall/morse*, the energy E is given by a Morse potential:
E = D_0 \left[ e^{- 2 \alpha (r - r_0)} - 2 e^{- \alpha (r - r_0)} \right]
\qquad r < r_c
.. versionadded:: TBD
.. versionadded:: 28Mar2023
For style *wall/lepton*, the energy E is provided as an Lepton
expression string using "r" as the distance variable. The `Lepton
@ -209,13 +209,13 @@ it as a single keyword.
Optionally, the expression may use "rc" to refer to the cutoff distance
for the given wall. Further constants in the expression can be defined
in the same string as additional expressions separated by semi-colons.
in the same string as additional expressions separated by semicolons.
The expression "k*(r-rc)^2;k=100.0" represents a repulsive-only harmonic
spring as in fix *wall/harmonic* with a force constant *K* (same as
:math:`\epsilon` above) of 100 energy units. More details on the Lepton
expression strings are given below.
.. versionadded:: TBD
.. versionadded:: 28Mar2023
For style *wall/table*, the energy E and forces are determined from
interpolation tables listed in one or more files as a function of

38
doc/src/fix_wall_gran.rst
View File

@ -1,8 +1,11 @@
.. index:: fix wall/gran
.. index:: fix wall/gran/kk
fix wall/gran command
=====================
Accelerator Variants: *wall/gran/kk*
Syntax
""""""
@ -71,9 +74,9 @@ Examples
fix 1 all wall/gran hooke 200000.0 NULL 50.0 NULL 0.5 0 xplane -10.0 10.0
fix 1 all wall/gran hooke/history 200000.0 NULL 50.0 NULL 0.5 0 zplane 0.0 NULL
fix 2 all wall/gran hooke 100000.0 20000.0 50.0 30.0 0.5 1 zcylinder 15.0 wiggle z 3.0 2.0
fix 3 all wall/gran/region granular hooke 1000.0 50.0 tangential linear_nohistory 1.0 0.4 damping velocity region myBox
fix 4 all wall/gran/region granular jkr 1e5 1500.0 0.3 10.0 tangential mindlin NULL 1.0 0.5 rolling sds 500.0 200.0 0.5 twisting marshall region myCone
fix 5 all wall/gran/region granular dmt 1e5 0.2 0.3 10.0 tangential mindlin NULL 1.0 0.5 rolling sds 500.0 200.0 0.5 twisting marshall damping tsuji heat 10 region myCone temperature 1.0
fix 3 all wall/gran granular hooke 1000.0 50.0 tangential linear_nohistory 1.0 0.4 damping velocity region myBox
fix 4 all wall/gran granular jkr 1e5 1500.0 0.3 10.0 tangential mindlin NULL 1.0 0.5 rolling sds 500.0 200.0 0.5 twisting marshall region myCone
fix 5 all wall/gran granular dmt 1e5 0.2 0.3 10.0 tangential mindlin NULL 1.0 0.5 rolling sds 500.0 200.0 0.5 twisting marshall damping tsuji heat 10 region myCone temperature 1.0
fix 6 all wall/gran hooke 200000.0 NULL 50.0 NULL 0.5 0 xplane -10.0 10.0 contacts
Description
@ -120,18 +123,17 @@ material.
.. note::
As discussed on the page for :doc:`pair_style gran/\* <pair_gran>`,
versions of LAMMPS before 9Jan09 used a
different equation for Hertzian interactions. This means Hertizian
wall/particle interactions have also changed. They now include a
sqrt(radius) term which was not present before. Also the previous
versions used Kn and Kt from the pairwise interaction and hardwired
dampflag to 1, rather than letting them be specified directly. This
means you can set the values of the wall/particle coefficients
appropriately in the current code to reproduce the results of a
previous Hertzian monodisperse calculation. For example, for the
common case of a monodisperse system with particles of diameter 1, Kn,
Kt, gamma_n, and gamma_s should be set sqrt(2.0) larger than they were
previously.
versions of LAMMPS before 9Jan09 used a different equation for
Hertzian interactions. This means Hertizian wall/particle
interactions have also changed. They now include a sqrt(radius) term
which was not present before. Also the previous versions used Kn and
Kt from the pairwise interaction and hardwired dampflag to 1, rather
than letting them be specified directly. This means you can set the
values of the wall/particle coefficients appropriately in the current
code to reproduce the results of a previous Hertzian monodisperse
calculation. For example, for the common case of a monodisperse
system with particles of diameter 1, Kn, Kt, gamma_n, and gamma_s
should be set sqrt(2.0) larger than they were previously.
The effective mass *m_eff* in the formulas listed on the :doc:`pair_style granular <pair_gran>` page is the mass of the particle for
particle/wall interactions (mass of wall is infinite). If the
@ -190,6 +192,12 @@ conduction model defined in :doc:`pair_style granular <pair_granular>`,
heat flow, and :doc:`fix heat/flow <fix_heat_flow>` to integrate heat
flow.
----------
.. include:: accel_styles.rst
----------
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

4
doc/src/improper_amoeba.rst
View File

@ -1,7 +1,7 @@
.. index:: improper_style amoeba
improper_style harmonic command
===============================
improper_style amoeba command
=============================
Syntax
""""""

3
doc/src/kspace_modify.rst
View File

@ -142,7 +142,8 @@ the code will stop with an error message. When this option is set to
For a typical application, using the automatic parameter generation
will provide simulations that are either inaccurate or slow. Using this
option is thus not recommended. For guidelines on how to obtain good
parameters, see the :doc:`How-To <Howto_dispersion>` discussion.
parameters, see the :doc:`long-range dispersion howto <Howto_dispersion>`
discussion.
----------

21
doc/src/mdi.rst
View File

@ -17,7 +17,7 @@ Syntax
*engine* args = zero or more keyword/args pairs
keywords = *elements*
*elements* args = N_1 N_2 ... N_ntypes
N_1,N_2,...N_ntypes = atomic number for each of ntypes LAMMPS atom types
N_1,N_2,...N_ntypes = chemical symbol for each of ntypes LAMMPS atom types
*plugin* args = name keyword value keyword value ...
name = name of plugin library (e.g., *lammps* means a liblammps.so library will be loaded)
keyword/value pairs in any order, some are required, some are optional
@ -35,7 +35,7 @@ Examples
.. code-block:: LAMMPS
mdi engine
mdi engine elements 13 29
mdi engine elements Al Cu
mdi plugin lammps mdi "-role ENGINE -name lammps -method LINK" &
infile in.aimd.engine extra "-log log.aimd.engine.plugin" &
command "run 5"
@ -173,13 +173,16 @@ commands, which are described further below.
atom type values are consistent in both codes, then the >TYPES
command can be used. If not, the optional *elements* keyword can
be used to specify what element each LAMMPS atom type corresponds
to. This is specified by the atomic number of the element (e.g., 13
for Al). An atomic number must be specified for each of the ntypes
LAMMPS atom types. Ntypes is typically specified via the
create_box command or in the data file read by the read_data
command. In this has been done, the MDI driver can send an
>ELEMENTS command to the LAMMPS driver with the atomic number of
each atom.
to. This is specified by the chemical symbol of the element,
e.g. C or Al or Si. A symbol must be specified for each of the
ntypes LAMMPS atom types. Each LAMMPS type must map to a unique
element; two or more types cannot map to the same element. Ntypes
is typically specified via the :doc:`create_box <create_box>`
command or in the data file read by the :doc:`read_data
<read_data>` command. Once this has been done, the MDI driver can
send an >ELEMENTS command to the LAMMPS driver with the atomic
number of each atom and the LAMMPS engine will be able to map it to
a LAMMPS atom type.
The MD and OPTG commands perform an entire MD simulation or energy
minimization (to convergence) with no communication from the driver

33
doc/src/neighbor.rst
View File

@ -59,9 +59,21 @@ long cutoff, but other type pairs have a much shorter cutoff. The
sized particles, where "size" may mean the physical size of the particle
or its cutoff distance for interacting with other particles. Different
sets of bins are then used to construct the neighbor lists as as further
described by Shire, Hanley, and Stratford :ref:`(Shire) <bytype-Shire>`.
This imposes some extra setup overhead, but the searches themselves may
be much faster. By default, each atom type defines a separate collection
described by Shire, Hanley, and Stratford :ref:`(Shire) <multi-Shire>`
and Monti et al. :ref:`(Monti) <multi-Monti>`. This imposes some extra
setup overhead, but the searches themselves may be much faster.
For instance in a dense binary system in d-dimensions with a ratio of the size
of the largest to smallest collection bin :math:`\lambda`, the computational
costs of building a default neighbor list grows as :math:`\lambda^{2d}` while
the costs for *multi* grows as :math:`\lambda^d`, equivalent to the cost
of force evaluations, as argued in Monti et al. :ref:`(Monti) <multi-Monti>`.
In other words, the neighboring costs of *multi* are expected to scale the
same as force calculations, such that its relative cost is independent of
the particle size ratio. This is not the case for the default style which
becomes substantially more expensive with increasing size ratios.
By default in *multi*, each atom type defines a separate collection
of particles. For systems where two or more atom types have the same
size (either physical size or cutoff distance), the definition of
collections can be customized, which can result in less overhead and
@ -75,8 +87,11 @@ An alternate style, *multi/old*, sets the bin size to 1/2 of the shortest
cutoff distance and multiple sets of bins are defined to search over for
different atom types. This algorithm used to be the default *multi*
algorithm in LAMMPS but was found to be significantly slower than the new
approach. For now we are keeping the old option in case there are use cases
where multi/old outperforms the new multi style.
approach. For the dense binary system, computational costs still grew as
:math:`\lambda^{2d}` at large enough :math:`\lambda`. This is equivalent
to the default style, albeit with a smaller prefactor. For now we are
keeping the old option in case there are use cases where multi/old
outperforms the new multi style.
.. note::
@ -118,6 +133,10 @@ Default
----------
.. _bytype-Shire:
.. _multi-Shire:
**(Shire)** Shire, Hanley and Stratford, Comp Part Mech, (2020).
**(Shire)** Shire, Hanley and Stratford, Comp. Part. Mech., (2020).
.. _multi-Monti:
**(Monti)** Monti, Clemmer, Srivastava, Silbert, Grest, and Lechman, Phys. Rev. E, (2022).

28
doc/src/package.rst
View File

@ -71,7 +71,7 @@ Syntax
*no_affinity* values = none
*kokkos* args = keyword value ...
zero or more keyword/value pairs may be appended
keywords = *neigh* or *neigh/qeq* or *neigh/thread* or *neigh/transpose* or *newton* or *binsize* or *comm* or *comm/exchange* or *comm/forward* or *comm/pair/forward* or *comm/fix/forward* or *comm/reverse* or *comm/pair/reverse* or *gpu/aware* or *pair/only*
keywords = *neigh* or *neigh/qeq* or *neigh/thread* or *neigh/transpose* or *newton* or *binsize* or *comm* or *comm/exchange* or *comm/forward* or *comm/pair/forward* or *comm/fix/forward* or *comm/reverse* or *comm/pair/reverse* or *sort* or *gpu/aware* or *pair/only*
*neigh* value = *full* or *half*
full = full neighbor list
half = half neighbor list built in thread-safe manner
@ -102,6 +102,9 @@ Syntax
*comm/pair/reverse* value = *no* or *device*
*no* = perform communication pack/unpack in non-KOKKOS mode
*device* = perform pack/unpack on device (e.g. on GPU)
*sort* value = *no* or *device*
*no* = perform atom sorting in non-KOKKOS mode
*device* = perform atom sorting on device (e.g. on GPU)
*gpu/aware* = *off* or *on*
*off* = do not use GPU-aware MPI
*on* = use GPU-aware MPI (default)
@ -554,6 +557,17 @@ pack/unpack communicated data. When running small systems on a GPU,
performing the exchange pack/unpack on the host CPU can give speedup
since it reduces the number of CUDA kernel launches.
The *sort* keyword determines whether the host or device performs atom
sorting, see the :doc:`atom_modify sort <atom_modify>` command. The
value options for the *sort* keyword are *no* or *device* similar to the
*comm* keywords above. If a value of *host* is used it will be
automatically be changed to *no* since the *sort* keyword does not
support *host* mode. The value of *no* will also always be used when
running on the CPU, i.e. setting the value to *device* will have no
effect if the simulation is running on the CPU. Not all fix styles with
extra atom data support *device* mode and in that case a warning will be
given and atom sorting will run in *no* mode instead.
The *gpu/aware* keyword chooses whether GPU-aware MPI will be used. When
this keyword is set to *on*, buffers in GPU memory are passed directly
through MPI send/receive calls. This reduces overhead of first copying
@ -705,12 +719,12 @@ script or via the "-pk intel" :doc:`command-line switch <Run_options>`.
For the KOKKOS package, the option defaults for GPUs are neigh = full,
neigh/qeq = full, newton = off, binsize for GPUs = 2x LAMMPS default
value, comm = device, neigh/transpose = off, gpu/aware = on. When
LAMMPS can safely detect that GPU-aware MPI is not available, the
default value of gpu/aware becomes "off". For CPUs or Xeon Phis, the
option defaults are neigh = half, neigh/qeq = half, newton = on,
binsize = 0.0, and comm = no. The option neigh/thread = on when there
are 16K atoms or less on an MPI rank, otherwise it is "off". These
value, comm = device, sort = device, neigh/transpose = off, gpu/aware =
on. When LAMMPS can safely detect that GPU-aware MPI is not available,
the default value of gpu/aware becomes "off". For CPUs or Xeon Phis, the
option defaults are neigh = half, neigh/qeq = half, newton = on, binsize
= 0.0, comm = no, and sort = no. The option neigh/thread = on when
there are 16K atoms or less on an MPI rank, otherwise it is "off". These
settings are made automatically by the required "-k on"
:doc:`command-line switch <Run_options>`. You can change them by using
the package kokkos command in your input script or via the :doc:`-pk

22
doc/src/pair_amoeba.rst
View File

@ -94,22 +94,22 @@ The formulas for the AMOEBA energy terms are:
.. math::
U_{hal} = \epsilon_{ij} \left( \frac{1.07}{\rho_{ij} + 0.07} \right)^7 \left( \frac{1.12}{\rho_{ij}^7 + 0.12} - 2 \right)
U_{multipole} = \vec{M_i}\bold{T_{ij}}\vec{M_j}
\vec{M} = \left( q, \vec{\mu_{perm}}, \bold{\Theta} \right)
U_{polar} = \frac{1}{2}\vec{\mu_i}^{ind} \vec{E_i}^{perm}
U_{hal} = & \epsilon_{ij} \left( \frac{1.07}{\rho_{ij} + 0.07} \right)^7 \left( \frac{1.12}{\rho_{ij}^7 + 0.12} - 2 \right) \\
U_{multipole} = & \vec{M}_i\boldsymbol{T_{ij}}\vec{M}_j, \quad \mbox{with} \quad
\vec{M} = \left(q, \vec{\mu}_{perm}, \boldsymbol{\Theta} \right) \\
U_{polar} = & \frac{1}{2}\vec{\mu}_i^{ind} \vec{E}_i^{perm}
The formulas for the HIPPO energy terms are:
.. math::
U_{multipole} = Z_i \frac{1}{r_{ij}} Z_j + Z_i T_{ij}^{damp} \vec{M_j} + Z_j T_{ji}^{damp} \vec{M_i} + \vec{M_i} T_{ij}^{damp} \vec{M_j}
\vec{M} = \left( Q, \vec{\mu_{perm}}, \bold{\Theta} \right)
U_{polar} = \frac{1}{2}\vec{\mu_i}^{ind} \vec{E_i}^{perm}
U_{qxfer} = \epsilon_i e^{-\eta_j r_{ij}} + \epsilon_j e^{-\eta_i r_{ij}}
U_{repulsion} = \frac{K_i K_j}{r_{ij}} S^2
S^2 = \left( \int{\phi_i \phi_j} dv \right)^2 = \vec{M_i}\bold{T_{ij}^{repulsion}}\vec{M_j}
U_{dispersion} = -\frac{C_6^iC_6^j}{r_{ij}^6} \left( f_{damp}^{dispersion} \right)_{ij}^2
U_{multipole} = & Z_i \frac{1}{r_{ij}} Z_j + Z_i T_{ij}^{damp} \vec{M}_j + Z_j T_{ji}^{damp} \vec{M}_i + \vec{M}_i T_{ij}^{damp} \vec{M}_j, \quad \mbox{with} \quad
\vec{M} = \left(q, \vec{\mu}_{perm}, \boldsymbol{\Theta} \right) \\
U_{polar} = & \frac{1}{2}\vec{\mu}_i^{ind} \vec{E}_i^{perm} \\
U_{qxfer} = & \epsilon_i e^{-\eta_j r_{ij}} + \epsilon_j e^{-\eta_i r_{ij}} \\
U_{repulsion} = & \frac{K_i K_j}{r_{ij}} S^2
S^2 = \left( \int{\phi_i \phi_j} dv \right)^2 = \vec{M}_i\boldsymbol{T_{ij}^{repulsion}}\vec{M}_j \\
U_{dispersion} = & -\frac{C_6^iC_6^j}{r_{ij}^6} \left( f_{damp}^{dispersion} \right)_{ij}^2
.. note::

103
doc/src/pair_born_gauss.rst Normal file
View File

@ -0,0 +1,103 @@
.. index:: pair_style born/gauss
pair_style born/gauss command
=============================
Syntax
""""""
.. code-block:: LAMMPS
pair_style born/gauss cutoff
* born/gauss = name of the pair style
* cutoff = global cutoff (distance units)
Examples
""""""""
.. code-block:: LAMMPS
pair_style born/gauss 10.0
pair_coeff 1 1 1 1 8.2464e13 12.48 0.042644277 0.44 3.56
Description
"""""""""""
.. versionadded:: 28Mar2023
Pair style *born/gauss* computes pairwise interactions from a combination of a Born-Mayer
repulsive term and a Gaussian attractive term according to :ref:`(Bomont) <Bomont>`:
.. math::
E = A_0 \exp \left( -\alpha r \right) - A_1 \exp\left[ -\beta \left(r - r_0 \right)^2 \right]
\qquad r < r_c
:math:`r_c` is the cutoff.
The following coefficients must be defined for each pair of atoms
types via the :doc:`pair_coeff <pair_coeff>` command as in the examples
above, or in the data file or restart files read by the
:doc:`read_data <read_data>` or :doc:`read_restart <read_restart>`
commands:
* :math:`A_0` (energy units)
* :math:`\alpha` (1/distance units)
* :math:`A_1` (energy units)
* :math:`\beta` (1/(distance units)^2)
* :math:`r_0` (distance units)
* cutoff (distance units)
The last coefficient is optional. If not specified, the global cutoff is used.
----------
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
This pair style does not support mixing. Thus, coefficients for all I,J
pairs must be specified explicitly.
This pair style supports the :doc:`pair_modify <pair_modify>` shift
option for the energy of the pair interaction.
The :doc:`pair_modify <pair_modify>` table options are not relevant for
this pair style.
This pair style does not support the :doc:`pair_modify <pair_modify>`
tail option for adding long-range tail corrections to energy and
pressure.
This pair style writes its information to :doc:`binary restart files
<restart>`, so pair_style and pair_coeff commands do not need to be
specified in an input script that reads a restart file.
This pair style can only be used via the *pair* keyword of the
:doc:`run_style respa <run_style>` command. It does not support the
*inner*, *middle*, *outer* keywords.
----------
Restrictions
""""""""""""
This pair style is only enabled if LAMMPS was built with the EXTRA-PAIR
package. See the :doc:`Build package <Build_package>` page for more
info.
Related commands
""""""""""""""""
:doc:`pair_coeff <pair_coeff>`, :doc:`pair_style born <pair_born>`
Default
"""""""
none
--------------
.. _Bomont:
**(Bomont)** Bomont, Bretonnet, J. Chem. Phys. 124, 054504 (2006)

2
doc/src/pair_colloid.rst
View File

@ -93,7 +93,7 @@ with :math:`A_{ss}` set appropriately, which results from letting both
particle sizes go to zero.
When used in combination with :doc:`pair_style yukawa/colloid
<pair_colloid>`, the two terms become the so-called DLVO potential,
<pair_yukawa_colloid>`, the two terms become the so-called DLVO potential,
which combines electrostatic repulsion and van der Waals attraction.
The following coefficients must be defined for each pair of atoms

66
doc/src/pair_dipole.rst
View File

@ -96,29 +96,29 @@ force (F), and torque (T) between particles I and J.
\left(\frac{\sigma}{r}\right)^6 \right] \\
E_{qq} = & \frac{q_i q_j}{r} \\
E_{qp} = & \frac{q}{r^3} (p \bullet \vec{r}) \\
E_{pp} = & \frac{1}{r^3} (\vec{p_i} \bullet \vec{p_j}) -
\frac{3}{r^5} (\vec{p_i} \bullet \vec{r}) (\vec{p_j} \bullet \vec{r}) \\
E_{pp} = & \frac{1}{r^3} (\vec{p}_i \bullet \vec{p}_j) -
\frac{3}{r^5} (\vec{p}_i \bullet \vec{r}) (\vec{p}_j \bullet \vec{r}) \\
& \\
F_{qq} = & \frac{q_i q_j}{r^3} \vec{r} \\
F_{qp} = & -\frac{q}{r^3} \vec{p} + \frac{3q}{r^5}
(\vec{p} \bullet \vec{r}) \vec{r} \\
F_{pp} = & \frac{3}{r^5} (\vec{p_i} \bullet \vec{p_j}) \vec{r} -
\frac{15}{r^7} (\vec{p_i} \bullet \vec{r})
(\vec{p_j} \bullet \vec{r}) \vec{r} +
\frac{3}{r^5} \left[ (\vec{p_j} \bullet \vec{r}) \vec{p_i} +
(\vec{p_i} \bullet \vec{r}) \vec{p_j} \right] \\
F_{pp} = & \frac{3}{r^5} (\vec{p}_i \bullet \vec{p}_j) \vec{r} -
\frac{15}{r^7} (\vec{p}_i \bullet \vec{r})
(\vec{p}_j \bullet \vec{r}) \vec{r} +
\frac{3}{r^5} \left[ (\vec{p}_j \bullet \vec{r}) \vec{p}_i +
(\vec{p}_i \bullet \vec{r}) \vec{p}_j \right] \\
& \\
T_{pq} = T_{ij} = & \frac{q_j}{r^3} (\vec{p_i} \times \vec{r}) \\
T_{qp} = T_{ji} = & - \frac{q_i}{r^3} (\vec{p_j} \times \vec{r}) \\
T_{pp} = T_{ij} = & -\frac{1}{r^3} (\vec{p_i} \times \vec{p_j}) +
\frac{3}{r^5} (\vec{p_j} \bullet \vec{r})
(\vec{p_i} \times \vec{r}) \\
T_{pp} = T_{ji} = & -\frac{1}{r^3} (\vec{p_j} \times \vec{p_i}) +
\frac{3}{r^5} (\vec{p_i} \bullet \vec{r})
(\vec{p_j} \times \vec{r})
T_{pq} = T_{ij} = & \frac{q_j}{r^3} (\vec{p}_i \times \vec{r}) \\
T_{qp} = T_{ji} = & - \frac{q_i}{r^3} (\vec{p}_j \times \vec{r}) \\
T_{pp} = T_{ij} = & -\frac{1}{r^3} (\vec{p}_i \times \vec{p}_j) +
\frac{3}{r^5} (\vec{p}_j \bullet \vec{r})
(\vec{p}_i \times \vec{r}) \\
T_{pp} = T_{ji} = & -\frac{1}{r^3} (\vec{p}_j \times \vec{p}_i) +
\frac{3}{r^5} (\vec{p}_i \bullet \vec{r})
(\vec{p}_j \times \vec{r})
where :math:`q_i` and :math:`q_j` are the charges on the two
particles, :math:`\vec{p_i}` and :math:`\vec{p_j}` are the dipole
particles, :math:`\vec{p}_i` and :math:`\vec{p}_j` are the dipole
moment vectors of the two particles, r is their separation distance,
and the vector r = Ri - Rj is the separation vector between the two
particles. Note that Eqq and Fqq are simply Coulombic energy and
@ -163,8 +163,8 @@ energy (E), force (F), and torque (T) between particles I and J:
2\left(\frac{r}{r_c}\right)^{\!3}\right] (\vec{p}\bullet\vec{r}) \\
E_{pp} = & \left[1-4\left(\frac{r}{r_c}\right)^{\!3} +
3\left(\frac{r}{r_c}\right)^{\!4}\right]\left[\frac{1}{r^3}
(\vec{p_i} \bullet \vec{p_j}) - \frac{3}{r^5}
(\vec{p_i} \bullet \vec{r}) (\vec{p_j} \bullet \vec{r})\right] \\
(\vec{p}_i \bullet \vec{p}_j) - \frac{3}{r^5}
(\vec{p}_i \bullet \vec{r}) (\vec{p}_j \bullet \vec{r})\right] \\
& \\
F_{LJ} = & \left\{\left[48\epsilon \left(\frac{\sigma}{r}\right)^{\!12} -
@ -182,37 +182,37 @@ energy (E), force (F), and torque (T) between particles I and J:
\frac{q}{r^3}\left[1-3\left(\frac{r}{r_c}\right)^{\!2} +
2\left(\frac{r}{r_c}\right)^{\!3}\right] \vec{p} \\
F_{pp} = &\frac{3}{r^5}\Bigg\{\left[1-\left(\frac{r}{r_c}\right)^{\!4}\right]
\left[(\vec{p_i}\bullet\vec{p_j}) - \frac{3}{r^2} (\vec{p_i}\bullet\vec{r})
(\vec{p_j} \bullet \vec{r})\right] \vec{r} + \\
\left[(\vec{p}_i\bullet\vec{p}_j) - \frac{3}{r^2} (\vec{p}_i\bullet\vec{r})
(\vec{p}_j \bullet \vec{r})\right] \vec{r} + \\
& \left[1 -
4\left(\frac{r}{r_c}\right)^{\!3}+3\left(\frac{r}{r_c}\right)^{\!4}\right]
\left[ (\vec{p_j} \bullet \vec{r}) \vec{p_i} + (\vec{p_i} \bullet \vec{r})
\vec{p_j} -\frac{2}{r^2} (\vec{p_i} \bullet \vec{r})
(\vec{p_j} \bullet \vec{r})\vec{r}\right] \Bigg\}
\left[ (\vec{p}_j \bullet \vec{r}) \vec{p}_i + (\vec{p}_i \bullet \vec{r})
\vec{p}_j -\frac{2}{r^2} (\vec{p}_i \bullet \vec{r})
(\vec{p}_j \bullet \vec{r})\vec{r}\right] \Bigg\}
.. math::
T_{pq} = T_{ij} = & \frac{q_j}{r^3} \left[ 1 -
3\left(\frac{r}{r_c}\right)^{\!2} +
2\left(\frac{r}{r_c}\right)^{\!3}\right] (\vec{p_i}\times\vec{r}) \\
2\left(\frac{r}{r_c}\right)^{\!3}\right] (\vec{p}_i\times\vec{r}) \\
T_{qp} = T_{ji} = & - \frac{q_i}{r^3} \left[ 1 -
3\left(\frac{r}{r_c}\right)^{\!2} +
2\left(\frac{r}{r_c}\right)^{\!3} \right] (\vec{p_j}\times\vec{r}) \\
2\left(\frac{r}{r_c}\right)^{\!3} \right] (\vec{p}_j\times\vec{r}) \\
T_{pp} = T_{ij} = & -\frac{1}{r^3}\left[1-4\left(\frac{r}{r_c}\right)^{\!3} +
e3\left(\frac{r}{r_c}\right)^{\!4}\right] (\vec{p_i} \times \vec{p_j}) + \\
e3\left(\frac{r}{r_c}\right)^{\!4}\right] (\vec{p}_i \times \vec{p}_j) + \\
& \frac{3}{r^5}\left[1-4\left(\frac{r}{r_c}\right)^{\!3} +
3\left(\frac{r}{r_c}\right)^{\!4}\right] (\vec{p_j}\bullet\vec{r})
(\vec{p_i} \times \vec{r}) \\
3\left(\frac{r}{r_c}\right)^{\!4}\right] (\vec{p}_j\bullet\vec{r})
(\vec{p}_i \times \vec{r}) \\
T_{pp} = T_{ji} = & -\frac{1}{r^3}\left[1-4\left(\frac{r}{r_c}\right)^{\!3} +
3\left(\frac{r}{r_c}\right)^{\!4}\right](\vec{p_j} \times \vec{p_i}) + \\
3\left(\frac{r}{r_c}\right)^{\!4}\right](\vec{p}_j \times \vec{p}_i) + \\
& \frac{3}{r^5}\left[1-4\left(\frac{r}{r_c}\right)^{\!3} +
3\left(\frac{r}{r_c}\right)^{\!4}\right] (\vec{p_i} \bullet \vec{r})
(\vec{p_j} \times \vec{r})
3\left(\frac{r}{r_c}\right)^{\!4}\right] (\vec{p}_i \bullet \vec{r})
(\vec{p}_j \times \vec{r})
where :math:`\epsilon` and :math:`\sigma` are the standard LJ
parameters, :math:`r_c` is the cutoff, :math:`q_i` and :math:`q_j` are
the charges on the two particles, :math:`\vec{p_i}` and
:math:`\vec{p_j}` are the dipole moment vectors of the two particles,
the charges on the two particles, :math:`\vec{p}_i` and
:math:`\vec{p}_j` are the dipole moment vectors of the two particles,
r is their separation distance, and the vector r = Ri - Rj is the
separation vector between the two particles. Note that Eqq and Fqq
are simply Coulombic energy and force, Fij = -Fji as symmetric forces,

36
doc/src/pair_dpd.rst
View File

@ -26,8 +26,8 @@ Syntax
pair_style dpd T cutoff seed
pair_style dpd/tstat Tstart Tstop cutoff seed
* T = temperature (temperature units)
* Tstart,Tstop = desired temperature at start/end of run (temperature units)
* T = temperature (temperature units) (dpd only)
* Tstart,Tstop = desired temperature at start/end of run (temperature units) (dpd/tstat only)
* cutoff = global cutoff for DPD interactions (distance units)
* seed = random # seed (positive integer)
@ -40,9 +40,9 @@ Examples
pair_coeff * * 3.0 1.0
pair_coeff 1 1 3.0 1.0 1.0
pair_style dpd/tstat 1.0 1.0 2.5 34387
pair_coeff * * 1.0
pair_coeff 1 1 1.0 1.0
pair_style hybrid/overlay lj/cut 2.5 dpd/tstat 1.0 1.0 2.5 34387
pair_coeff * * lj/cut 1.0 1.0
pair_coeff * * dpd/tstat 1.0
Description
"""""""""""
@ -53,7 +53,7 @@ Style *dpd* computes a force field for dissipative particle dynamics
Style *dpd/tstat* invokes a DPD thermostat on pairwise interactions,
which is equivalent to the non-conservative portion of the DPD force
field. This pairwise thermostat can be used in conjunction with any
:doc:`pair style <pair_style>`, and in leiu of per-particle thermostats
:doc:`pair style <pair_style>`, and instead of per-particle thermostats
like :doc:`fix langevin <fix_langevin>` or ensemble thermostats like
Nose Hoover as implemented by :doc:`fix nvt <fix_nh>`. To use
*dpd/tstat* as a thermostat for another pair style, use the
@ -68,13 +68,13 @@ of 3 terms
\vec{f} = & (F^C + F^D + F^R) \hat{r_{ij}} \qquad \qquad r < r_c \\
F^C = & A w(r) \\
F^D = & - \gamma w^2(r) (\hat{r_{ij}} \bullet \vec{v_{ij}}) \\
F^D = & - \gamma w^2(r) (\hat{r_{ij}} \bullet \vec{v}_{ij}) \\
F^R = & \sigma w(r) \alpha (\Delta t)^{-1/2} \\
w(r) = & 1 - \frac{r}{r_c}
where :math:`F^C` is a conservative force, :math:`F^D` is a dissipative
force, and :math:`F^R` is a random force. :math:`\hat{r_{ij}}` is a
unit vector in the direction :math:`r_i - r_j`, :math:`\vec{v_{ij}}` is
unit vector in the direction :math:`r_i - r_j`, :math:`\vec{v}_{ij}` is
the vector difference in velocities of the two atoms :math:`\vec{v}_i -
\vec{v}_j`, :math:`\alpha` is a Gaussian random number with zero mean
and unit variance, *dt* is the timestep size, and :math:`w(r)` is a
@ -105,14 +105,18 @@ commands:
* :math:`\gamma` (force/velocity units)
* cutoff (distance units)
The last coefficient is optional. If not specified, the global DPD
The cutoff coefficient is optional. If not specified, the global DPD
cutoff is used. Note that sigma is set equal to sqrt(2 T gamma),
where T is the temperature set by the :doc:`pair_style <pair_style>`
command so it does not need to be specified.
For style *dpd/tstat*, the coefficients defined for each pair of
atoms types via the :doc:`pair_coeff <pair_coeff>` command is the same,
except that A is not included.
atoms types via the :doc:`pair_coeff <pair_coeff>` command are:
* :math:`\gamma` (force/velocity units)
* cutoff (distance units)
The cutoff coefficient is optional.
The GPU-accelerated versions of these styles are implemented based on
the work of :ref:`(Afshar) <Afshar>` and :ref:`(Phillips) <Phillips>`.
@ -135,6 +139,12 @@ the work of :ref:`(Afshar) <Afshar>` and :ref:`(Phillips) <Phillips>`.
numbers are applied and thus the individual forces and therefore
also the virial/pressure.
.. note::
For more consistent time integration and force computation you may
consider using :doc:`fix mvv/dpd <fix_mvv_dpd>` instead of :doc:`fix
nve <fix_nve>`.
----------
.. include:: accel_styles.rst
@ -206,7 +216,9 @@ command for more details.
Related commands
""""""""""""""""
:doc:`pair_coeff <pair_coeff>`, :doc:`fix nvt <fix_nh>`, :doc:`fix langevin <fix_langevin>`, :doc:`pair_style srp <pair_srp>`
:doc:`pair_style dpd/ext <pair_dpd_ext>`, :doc:`pair_coeff <pair_coeff>`,
:doc:`fix nvt <fix_nh>`, :doc:`fix langevin <fix_langevin>`,
:doc:`pair_style srp <pair_srp>`, :doc:`fix mvv/dpd <fix_mvv_dpd>`.
Default
"""""""

39
doc/src/pair_dpd_ext.rst
View File

@ -18,7 +18,6 @@ Accelerator Variants: dpd/ext/tstat/kk dpd/ext/tstat/omp
Syntax
""""""
.. code-block:: LAMMPS
pair_style dpd/ext T cutoff seed
@ -32,16 +31,15 @@ Syntax
Examples
""""""""
.. code-block:: LAMMPS
pair_style dpd/ext 1.0 2.5 34387
pair_coeff 1 1 25.0 4.5 4.5 0.5 0.5 1.2
pair_coeff 1 2 40.0 4.5 4.5 0.5 0.5 1.2
pair_style dpd/ext/tstat 1.0 1.0 2.5 34387
pair_coeff 1 1 4.5 4.5 0.5 0.5 1.2
pair_coeff 1 2 4.5 4.5 0.5 0.5 1.2
pair_style hybrid/overlay lj/cut 2.5 dpd/ext/tstat 1.0 1.0 2.5 34387
pair_coeff * * lj/cut 1.0 1.0
pair_coeff * * 4.5 4.5 0.5 0.5 1.2
Description
"""""""""""
@ -128,20 +126,39 @@ the :doc:`pair_style <pair_style>` command so it does not need to be
specified.
For the style *dpd/ext/tstat*, the coefficients defined for each pair of
atoms types via the :doc:`pair_coeff <pair_coeff>` command is the same,
except that A is not included.
atoms types via the :doc:`pair_coeff <pair_coeff>` command are:
* :math:`\gamma_{\parallel}` (force/velocity units)
* :math:`\gamma_{\perp}` (force/velocity units)
* :math:`s_{\parallel}` (unitless)
* :math:`s_{\perp}` (unitless)
* :math:`r_c` (distance units)
The last coefficient is optional.
.. note::
If you are modeling DPD polymer chains, you may want to use the
:doc:`pair_style srp <pair_srp>` command in conjunction with these pair
styles. It is a soft segmental repulsive potential (SRP) that can
styles. It is a soft segmental repulsive potential (SRP) that can
prevent DPD polymer chains from crossing each other.
.. note::
The virial calculation for pressure when using this pair style includes
all the components of force listed above, including the random force.
The virial calculation for pressure when using these pair styles
includes all the components of force listed above, including the
random force. Since the random force depends on random numbers,
everything that changes the order of atoms in the neighbor list
(e.g. different number of MPI ranks or a different neighbor list
skin distance) will also change the sequence in which the random
numbers are applied and thus the individual forces and therefore
also the virial/pressure.
.. note::
For more consistent time integration and force computation you may
consider using :doc:`fix mvv/dpd <fix_mvv_dpd>` instead of :doc:`fix
nve <fix_nve>`.
----------
@ -207,7 +224,7 @@ Related commands
:doc:`pair_style dpd <pair_dpd>`, :doc:`pair_coeff <pair_coeff>`,
:doc:`fix nvt <fix_nh>`, :doc:`fix langevin <fix_langevin>`,
:doc:`pair_style srp <pair_srp>`
:doc:`pair_style srp <pair_srp>`, :doc:`fix mvv/dpd <fix_mvv_dpd>`.
**Default:** none

8
doc/src/pair_dpd_fdt.rst
View File

@ -56,13 +56,13 @@ given as a sum of 3 terms
\vec{f} = & (F^C + F^D + F^R) \hat{r_{ij}} \qquad \qquad r < r_c \\
F^C = & A w(r) \\
F^D = & - \gamma w^2(r) (\hat{r_{ij}} \bullet \vec{v_{ij}}) \\
F^D = & - \gamma w^2(r) (\hat{r_{ij}} \bullet \vec{v}_{ij}) \\
F^R = & \sigma w(r) \alpha (\Delta t)^{-1/2} \\
w(r) = & 1 - \frac{r}{r_c}
where :math:`F^C` is a conservative force, :math:`F^D` is a dissipative
force, and :math:`F^R` is a random force. :math:`\hat{r_{ij}}` is a
unit vector in the direction :math:`r_i - r_j`, :math:`\vec{v_{ij}}` is
unit vector in the direction :math:`r_i - r_j`, :math:`\vec{v}_{ij}` is
the vector difference in velocities of the two atoms, :math:`\vec{v}_i -
\vec{v}_j`, :math:`\alpha` is a Gaussian random number with zero mean
and unit variance, *dt* is the timestep size, and :math:`w(r)` is a
@ -99,9 +99,9 @@ energies are computed within style *dpd/fdt/energy* as:
.. math::
du_{i}^{cond} = & \kappa_{ij}(\frac{1}{\theta_{i}}-\frac{1}{\theta_{j}})\omega_{ij}^{2} + \alpha_{ij}\omega_{ij}\zeta_{ij}^{q}(\Delta{t})^{-1/2} \\
du_{i}^{mech} = & -\frac{1}{2}\gamma_{ij}\omega_{ij}^{2}(\frac{\vec{r_{ij}}}{r_{ij}}\bullet\vec{v_{ij}})^{2} -
du_{i}^{mech} = & -\frac{1}{2}\gamma_{ij}\omega_{ij}^{2}(\frac{\vec{r}_{ij}}{r_{ij}}\bullet\vec{v}_{ij})^{2} -
\frac{\sigma^{2}_{ij}}{4}(\frac{1}{m_{i}}+\frac{1}{m_{j}})\omega_{ij}^{2} -
\frac{1}{2}\sigma_{ij}\omega_{ij}(\frac{\vec{r_{ij}}}{r_{ij}}\bullet\vec{v_{ij}})\zeta_{ij}(\Delta{t})^{-1/2}
\frac{1}{2}\sigma_{ij}\omega_{ij}(\frac{\vec{r}_{ij}}{r_{ij}}\bullet\vec{v}_{ij})\zeta_{ij}(\Delta{t})^{-1/2}
where

2
doc/src/pair_gauss.rst
View File

@ -170,7 +170,7 @@ The *gauss* and *gauss/cut* styles are part of the EXTRA-PAIR package.
They are only enabled if LAMMPS is build with that package. See the
:doc:`Build package <Build_package>` page for more info.
.. versionchanged:: TBD
.. versionchanged:: 28Mar2023
Prior to this version, the *gauss* pair style did not apply
:doc:`special_bonds <special_bonds>` factors.

4
doc/src/pair_granular.rst
View File

@ -650,13 +650,13 @@ For *heat* *area*, the heat
.. math::
Q = k_{s} a \Delta T
Q = k_{s} A \Delta T
where :math:`\Delta T` is the difference in the two particles' temperature,
:math:`k_{s}` is a non-negative numeric value for the conductivity, and
:math:`a` is the area of the contact and depends on the normal force model.
:math:`A` is the area of the contact and depends on the normal force model.
Note that the option *none* must either be used in all or none of of the
*pair_coeff* calls. See :doc:`fix heat/flow <fix_heat_flow>` and

79
doc/src/pair_lepton.rst
View File

@ -2,11 +2,13 @@
.. index:: pair_style lepton/omp
.. index:: pair_style lepton/coul
.. index:: pair_style lepton/coul/omp
.. index:: pair_style lepton/sphere
.. index:: pair_style lepton/sphere/omp
pair_style lepton command
=========================
Accelerator Variants: *lepton/omp*, *lepton/coul/comp*
Accelerator Variants: *lepton/omp*, *lepton/coul/comp*, *lepton/sphere/comp*
Syntax
""""""
@ -15,7 +17,7 @@ Syntax
pair_style style args
* style = *lepton* or *lepton/coul*
* style = *lepton* or *lepton/coul* or *lepton/sphere*
* args = list of arguments for a particular style
.. parsed-literal::
@ -26,6 +28,8 @@ Syntax
cutoff = global cutoff for the interactions (distance units)
zero or more keywords may be appended
keyword = *ewald* or *pppm* or *msm* or *dispersion* or *tip4p*
*lepton/sphere* args = cutoff
cutoff = global cutoff for the interactions (distance units)
Examples
""""""""
@ -48,19 +52,32 @@ Examples
kspace_style pppm 1.0e-4
pair_coeff 1 1 "qi*qj/r*erfc(alpha*r); alpha=1.067"
pair_style lepton/sphere 2.5
pair_coeff 1 * "k*((r-r0)^2*step(r0-r)); k=200; r0=radi+radj"
pair_coeff 2 2 "4.0*eps*((sig/r)^12 - (sig/r)^6); eps=1.0; sig=2.0*sqrt(radi*radj)"
Description
"""""""""""
.. versionadded:: 8Feb2023
Pair styles *lepton* and *lepton/coul* compute pairwise interactions
between particles which depend solely on the distance and have a cutoff.
The potential function must be provided as an expression string using
"r" as the distance variable. With pair style *lepton/coul* one may
additionally reference the charges of the two atoms of the pair with
"qi" and "qj", respectively. Note that further constants in the
expression can be defined in the same string as additional expressions
separated by semi-colons as shown in the examples above.
.. versionchanged:: TBD
added pair style lepton/sphere
Pair styles *lepton*, *lepton/coul*, *lepton/sphere* compute pairwise
interactions between particles which depend on the distance and have a
cutoff. The potential function must be provided as an expression string
using "r" as the distance variable. With pair style *lepton/coul* one
may additionally reference the charges of the two atoms of the pair with
"qi" and "qj", respectively. With pair style *lepton/coul* one may
instead reference the radii of the two atoms of the pair with "radi" and
"radj", respectively; this is half of the diameter that can be set in
:doc:`data files <read_data>` or the :doc:`set command <set>`.
Note that further constants in the expressions can be defined in the
same string as additional expressions separated by semicolons as shown
in the examples above.
The expression `"200.0*(r-1.5)^2"` represents a harmonic potential
around the pairwise distance :math:`r_0` of 1.5 distance units and a
@ -76,6 +93,14 @@ The expression `"qi*qj/r"` represents a regular Coulombic potential with cutoff:
U_{ij} = \frac{C q_i q_j}{\epsilon r} \qquad r < r_c
The expression `"200.0*(r-(radi+radj)^2"` represents a harmonic potential
that has the equilibrium distance chosen so that the radii of the two
atoms touch:
.. math::
U_{ij} = K (r-(r_i+r_j))^2
The `Lepton library <https://simtk.org/projects/lepton>`_, that the
*lepton* pair style interfaces with, evaluates this expression string at
run time to compute the pairwise energy. It also creates an analytical
@ -97,13 +122,20 @@ More on valid Lepton expressions below. The last coefficient is
optional; it allows to set the cutoff for a pair of atom types to a
different value than the global cutoff.
For pair style *lepton* only the "lj" value of the :doc:`special_bonds <special_bonds>`
settings apply in case the interacting pair is also connected with a bond.
The potential energy will *only* be added to the "evdwl" property.
For pair style *lepton* only the "lj" values of the :doc:`special_bonds
<special_bonds>` settings apply in case the interacting pair is also
connected with a bond. The potential energy will *only* be added to the
"evdwl" property.
For pair style *lepton/coul* only the "coul" value of the :doc:`special_bonds <special_bonds>`
settings apply in case the interacting pair is also connected with a bond.
The potential energy will *only* be added to the "ecoul" property.
For pair style *lepton/coul* only the "coul" values of the
:doc:`special_bonds <special_bonds>` settings apply in case the
interacting pair is also connected with a bond. The potential energy
will *only* be added to the "ecoul" property.
For pair style *lepton/sphere* only the "lj" values of the
:doc:`special_bonds <special_bonds>` settings apply in case the
interacting pair is also connected with a bond. The potential energy
will *only* be added to the "evdwl" property.
In addition to the functions listed below, both pair styles support in
addition a custom "zbl(zi,zj,r)" function which computes the
@ -127,12 +159,13 @@ above.
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Pair styles *lepton* and *lepton/coul* do not support mixing. Thus,
expressions for *all* I,J pairs must be specified explicitly.
Pair styles *lepton*, *lepton/coul*, and *lepton/sphere* do not support
mixing. Thus, expressions for *all* I,J pairs must be specified
explicitly.
Only pair style *lepton* supports the :doc:`pair_modify shift <pair_modify>`
option for shifting the energy of the pair interaction so that it is
0 at the cutoff, pair style *lepton/coul* does *not*.
0 at the cutoff, pair styles *lepton/coul* and *lepton/sphere* do *not*.
The :doc:`pair_modify table <pair_modify>` options are not relevant for
the these pair styles.
@ -141,7 +174,7 @@ These pair styles do not support the :doc:`pair_modify tail
<pair_modify>` option for adding long-range tail corrections to energy
and pressure.
These pair styles write its information to :doc:`binary restart files
These pair styles write their information to :doc:`binary restart files
<restart>`, so pair_style and pair_coeff commands do not need to be
specified in an input script that reads a restart file.
@ -158,6 +191,12 @@ These pair styles are part of the LEPTON package and only enabled if
LAMMPS was built with this package. See the :doc:`Build package
<Build_package>` page for more info.
Pair style *lepton/coul* requires that atom atoms have a charge
property, e.g. via :doc:`atom_style charge <atom_style>`.
Pair style *lepton/sphere* requires that atom atoms have a radius
property, e.g. via :doc:`atom_style sphere <atom_style>`.
Related commands
""""""""""""""""

34
doc/src/pair_lj.rst
View File

@ -43,8 +43,7 @@ given by
.. math::
E = 4 \epsilon \left[ \left(\frac{\sigma}{r}\right)^{12} -
\left(\frac{\sigma}{r}\right)^6 \right]
\qquad r < r_c
\left(\frac{\sigma}{r}\right)^6 \right] \qquad r < r_c
:math:`r_c` is the cutoff.
@ -64,11 +63,23 @@ file or restart files read by the :doc:`read_data <read_data>` or
* :math:`\sigma` (distance units)
* LJ cutoff (distance units)
Note that :math:`\sigma` is defined in the LJ formula as the zero-crossing
distance for the potential, not as the energy minimum at :math:`2^{\frac{1}{6}} \sigma`.
The last coefficient is optional. If not specified, the global
LJ cutoff specified in the pair_style command are used.
LJ cutoff specified in the pair_style command is used.
Note that :math:`\sigma` is defined in the LJ formula as the
zero-crossing distance for the potential, *not* as the energy minimum at
:math:`r_0 = 2^{\frac{1}{6}} \sigma`. The _same_ potential function becomes:
.. math::
E = \epsilon \left[ \left(\frac{r_0}{r}\right)^{12} -
2 \left(\frac{r_0}{r}\right)^6 \right] \qquad r < r_c
When using the minimum as reference width. In the literature both
formulations are used, but the describe the same potential, only the
:math:`\sigma` value must be computed by :math:`\sigma = r_0 /
2^{\frac{1}{6}}` for use with LAMMPS, if this latter formulation is
used.
----------
@ -103,11 +114,12 @@ portion of the pair interaction.
All of the *lj/cut* pair styles write their information to :doc:`binary restart files <restart>`, so pair_style and pair_coeff commands do
not need to be specified in an input script that reads a restart file.
The *lj/cut* pair styles support the use of the
*inner*, *middle*, and *outer* keywords of the :doc:`run_style respa <run_style>` command, meaning the pairwise forces can be
partitioned by distance at different levels of the rRESPA hierarchy.
The other styles only support the *pair* keyword of run_style respa.
See the :doc:`run_style <run_style>` command for details.
The *lj/cut* pair styles support the use of the *inner*, *middle*, and
*outer* keywords of the :doc:`run_style respa <run_style>` command,
meaning the pairwise forces can be partitioned by distance at different
levels of the rRESPA hierarchy. The other styles only support the
*pair* keyword of run_style respa. See the :doc:`run_style <run_style>`
command for details.
----------

192
doc/src/pair_lj_cut_sphere.rst Normal file
View File

@ -0,0 +1,192 @@
.. index:: pair_style lj/cut/sphere
.. index:: pair_style lj/cut/sphere/omp
pair_style lj/cut/sphere command
================================
Accelerator Variant: *lj/cut/sphere/omp*
Syntax
""""""
.. code-block:: LAMMPS
pair_style style args
* style = *lj/cut/sphere*
* args = list of arguments for a particular style
.. parsed-literal::
*lj/cut/sphere* args = cutoff ratio
cutoff = global cutoff ratio for Lennard Jones interactions (unitless)
Examples
""""""""
.. code-block:: LAMMPS
pair_style lj/cut/sphere 2.5
pair_coeff * * 1.0
pair_coeff 1 1 1.1 2.8
Description
"""""""""""
.. versionadded:: TBD
The *lj/cut/sphere* style compute the standard 12/6 Lennard-Jones potential,
given by
.. math::
E = 4 \epsilon \left[ \left(\frac{\sigma_{ij}}{r}\right)^{12} -
\left(\frac{\sigma_{ij}}{r}\right)^6 \right] \qquad r < r_c * \sigma_{ij}
:math:`r_c` is the cutoff ratio.
This is the same potential function used by the :doc:`lj/cut
<pair_lj>` pair style, but the :math:`\sigma_{ij}` parameter is not
set as a per-type parameter via the :doc:`pair_coeff command
<pair_coeff>`. Instead it is calculated individually for each pair
using the per-atom diameter attribute of :doc:`atom_style sphere
<atom_style>` for the two atoms as :math:`\sigma_{i}` and
:math:`\sigma_{j}`; :math:`\sigma_{ij}` is then computed by the mixing
rule for pair coefficients as set by the :doc:`pair_modify mix
<pair_modify>` command (defaults to geometric mixing). The cutoff is
not specified as a distance, but as ratio that is internally
multiplied by :math:`\sigma_{ij}` to obtain the actual cutoff for each
pair of atoms.
Note that :math:`\sigma_{ij}` is defined in the LJ formula above as the
zero-crossing distance for the potential, *not* as the energy minimum which
is at :math:`2^{\frac{1}{6}} \sigma_{ij}`.
.. admonition:: Notes on cutoffs, neighbor lists, and efficiency
:class: note
If your system is mildly polydisperse, meaning the ratio of the
diameter of the largest particle to the smallest is less than 2.0,
then the neighbor lists built by the code should be reasonably
efficient. Which means they will not contain too many particle
pairs that do not interact. However, if your system is highly
polydisperse (ratio > 2.0), the neighbor list build and force
computations may be inefficient. There are two ways to try and
speed up the simulations.
The first is to assign atoms to different atom types so that atoms of
each type are similar in size. E.g. if particle diameters range from
1 to 5 use 4 atom types, ensuring atoms of type 1 have diameters from
1.0-2.0, type 2 from 2.0-3.0, etc. This will reduce the number of
non-interacting pairs in the neighbor lists and thus reduce the time
spent on computing pairwise interactions.
The second is to use the :doc:`neighbor multi <neighbor>` command
which enabled a different algorithm for building neighbor lists. This
will also require that you assign multiple atom types according to
diameters, but will in addition use a more efficient size-dependent
strategy to construct the neighbor lists and thus reduce the time
spent on building neighbor lists.
Here are example input script commands using both ideas for a
highly polydisperse system:
.. code-block:: c++
units lj
atom_style sphere
lattice fcc 0.8442
region box block 0 10 0 10 0 10
create_box 2 box
create_atoms 1 box
# create atoms with random diameters from bimodal distribution
variable switch atom random(0.0,1.0,345634)
variable diam atom (v_switch<0.75)*normal(0.4,0.075,325)+(v_switch>=0.7)*normal(1.2,0.2,453)
set group all diameter v_diam
# assign type 2 to atoms with diameter > 0.6
variable large atom (2.0*radius)>0.6
group large variable large
set group large type 2
pair_style lj/cut/sphere 2.5
pair_coeff * * 1.0
neighbor 0.3 multi
Using multiple atom types speeds up the calculation for this example
by more than a factor of 2, and using the multi-style neighbor list
build causes an additional speedup of about 20 percent.
Coefficients
""""""""""""
The following coefficients must be defined for each pair of atoms types via the
:doc:`pair_coeff <pair_coeff>` command as in the examples above, or in the data
file or restart files read by the :doc:`read_data <read_data>` or
:doc:`read_restart <read_restart>` commands, or by mixing as described below:
* :math:`\epsilon` (energy units)
* LJ cutoff ratio (unitless) (optional)
The last coefficient is optional. If not specified, the global LJ
cutoff ratio specified in the :doc:`pair_style command <pair_style>` is
used.
If a repulsive only LJ interaction is desired, the coefficient for the cutoff
ratio should be set to the minimum of the LJ potential using ``$(2.0^(1.0/6.0))``
----------
.. include:: accel_styles.rst
----------
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
For atom type pairs I,J and I != J, the epsilon coefficients and cutoff
ratio for the *lj/cut/sphere* pair style can be mixed. The default mixing
style is *geometric*. See the :doc:`pair_modify command <pair_modify>`
for details.
The *lj/cut/sphere* pair style supports the :doc:`pair_modify shift <pair_modify>`
option for the energy of the Lennard-Jones portion of the pair interaction.
The *lj/cut/sphere* pair style does *not* support the :doc:`pair_modify
<pair_modify>` tail option for adding a long-range tail corrections to
the energy and pressure.
The *lj/cut/sphere* pair style writes its information to :doc:`binary
restart files <restart>`, so pair_style and pair_coeff commands do not
need to be specified in an input script that reads a restart file.
This pair style can only be used via the *pair* keyword of the
:doc:`run_style respa <run_style>` command. It does *not* support the
*inner*, *middle*, *outer* keywords.
----------
Restrictions
""""""""""""
The *lj/cut/sphere* pair style is only enabled if LAMMPS was built with the
EXTRA-PAIR package. See the :doc:`Build package <Build_package>` page
for more info.
The *lj/cut/sphere* pair style does not support the *sixthpower* mixing rule.
----------
Related commands
""""""""""""""""
* :doc:`pair_coeff <pair_coeff>`
* :doc:`pair_style lj/cut <pair_lj>`
* :doc:`pair_style lj/expnd/sphere <pair_lj_expand_sphere>`
Default
"""""""
none

187
doc/src/pair_lj_expand_sphere.rst Normal file
View File

@ -0,0 +1,187 @@
.. index:: pair_style lj/expand/sphere
.. index:: pair_style lj/expand/sphere/omp
pair_style lj/expand/sphere command
===================================
Accelerator Variant: *lj/expand/sphere/omp*
Syntax
""""""
.. code-block:: LAMMPS
pair_style style args
* style = *lj/expand/sphere*
* args = list of arguments for a particular style
.. parsed-literal::
*lj/expand/sphere* args = cutoff
cutoff = global cutoff for Lennard Jones interactions (distance units)
Examples
""""""""
.. code-block:: LAMMPS
pair_style lj/expand/sphere 2.5
pair_coeff * * 1.0 1.0
pair_coeff 1 1 1.1 0.4 2.8
Description
"""""""""""
.. versionadded:: TBD
The *lj/expand/sphere* style compute a 12/6 Lennard-Jones potential with
a distance shifted by :math:`\Delta = \frac{1}{2} (d_i + d_j)`, the
average diameter of both atoms. This can be used to model particles of
different sizes but same interactions, which is different from using
different sigma values as in :doc:`pair style lj/cut/sphere
<pair_lj_cut_sphere>`.
.. math::
E = 4 \epsilon \left[ \left(\frac{\sigma}{r - \Delta}\right)^{12} -
\left(\frac{\sigma}{r - \Delta}\right)^6 \right]
\qquad r < r_c + \Delta
:math:`r_c` is the cutoff which does not include the distance :math:`\Delta`.
I.e. the actual force cutoff is the sum :math:`r_c + \Delta`.
This is the same potential function used by the :doc:`lj/expand
<pair_lj>` pair style, but the :math:`\Delta` parameter is not
set as a per-type parameter via the :doc:`pair_coeff command
<pair_coeff>`. Instead it is calculated individually for each pair
using the per-atom diameter attribute of :doc:`atom_style sphere
<atom_style>` for the two atoms as the average diameter, :math:`\Delta = \frac{1}{2} (d_i + d_j)`
Note that :math:`\sigma` is defined in the LJ formula above as the
zero-crossing distance for the potential, *not* as the energy minimum which
is at :math:`2^{\frac{1}{6}} \sigma`.
.. admonition:: Notes on cutoffs, neighbor lists, and efficiency
:class: note
If your system is mildly polydisperse, meaning the ratio of the
diameter of the largest particle to the smallest is less than 2.0,
then the neighbor lists built by the code should be reasonably
efficient. Which means they will not contain too many particle
pairs that do not interact. However, if your system is highly
polydisperse (ratio > 2.0), the neighbor list build and force
computations may be inefficient. There are two ways to try and
speed up the simulations.
The first is to assign atoms to different atom types so that atoms of
each type are similar in size. E.g. if particle diameters range from
1 to 5 use 4 atom types, ensuring atoms of type 1 have diameters from
1.0-2.0, type 2 from 2.0-3.0, etc. This will reduce the number of
non-interacting pairs in the neighbor lists and thus reduce the time
spent on computing pairwise interactions.
The second is to use the :doc:`neighbor multi <neighbor>` command
which enabled a different algorithm for building neighbor lists. This
will also require that you assign multiple atom types according to
diameters, but will in addition use a more efficient size-dependent
strategy to construct the neighbor lists and thus reduce the time
spent on building neighbor lists.
Here are example input script commands using the first option for a
highly polydisperse system:
.. code-block:: c++
units lj
atom_style sphere
lattice fcc 0.8442
region box block 0 10 0 10 0 10
create_box 2 box
create_atoms 1 box
# create atoms with random diameters from bimodal distribution
variable switch atom random(0.0,1.0,345634)
variable diam atom (v_switch<0.75)*normal(0.2,0.04,325)+(v_switch>=0.7)*normal(0.6,0.2,453)
set group all diameter v_diam
# assign type 2 to atoms with diameter > 0.35
variable large atom (2.0*radius)>0.35
group large variable large
set group large type 2
pair_style lj/expand/sphere 2.0
pair_coeff * * 1.0 0.5
neighbor 0.3 bin
Using multiple atom types speeds up the calculation for this example
by more than 30 percent, but using the multi-style neighbor list does
not provide a speedup.
Coefficients
""""""""""""
The following coefficients must be defined for each pair of atoms types via the
:doc:`pair_coeff <pair_coeff>` command as in the examples above, or in the data
file or restart files read by the :doc:`read_data <read_data>` or
:doc:`read_restart <read_restart>` commands, or by mixing as described below:
* :math:`\epsilon` (energy units)
* :math:`\sigma` (distance units)
* LJ cutoff (distance units) (optional)
The last coefficient is optional. If not specified, the global LJ
cutoff specified in the :doc:`pair_style command <pair_style>` is used.
----------
.. include:: accel_styles.rst
----------
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
For atom type pairs I,J and I != J, the epsilon, sigma, and cutoff
coefficients for the *lj/expand/sphere* pair style can be mixed. The
default mixing style is *geometric*. See the :doc:`pair_modify command
<pair_modify>` for details.
The *lj/expand/sphere* pair style supports the :doc:`pair_modify shift <pair_modify>`
option for the energy of the Lennard-Jones portion of the pair interaction.
The *lj/expand/sphere* pair style does *not* support the :doc:`pair_modify
<pair_modify>` tail option for adding a long-range tail corrections to
the energy and pressure.
The *lj/expand/sphere* pair style writes its information to :doc:`binary
restart files <restart>`, so pair_style and pair_coeff commands do not
need to be specified in an input script that reads a restart file.
This pair style can only be used via the *pair* keyword of the
:doc:`run_style respa <run_style>` command. It does *not* support the
*inner*, *middle*, *outer* keywords.
----------
Restrictions
""""""""""""
The *lj/expand/sphere* pair style is only enabled if LAMMPS was built with the
EXTRA-PAIR package. See the :doc:`Build package <Build_package>` page
for more info.
----------
Related commands
""""""""""""""""
* :doc:`pair_coeff <pair_coeff>`
* :doc:`pair_style lj/cut <pair_lj>`
* :doc:`pair_style lj/cut/sphere <pair_lj_cut_sphere>`
Default
"""""""
none

14
doc/src/pair_pace.rst
View File

@ -48,9 +48,9 @@ Description
Pair style *pace* computes interactions using the Atomic Cluster
Expansion (ACE), which is a general expansion of the atomic energy in
multi-body basis functions. :ref:`(Drautz) <Drautz20191>`. The *pace*
multi-body basis functions. :ref:`(Drautz19) <Drautz20191>`. The *pace*
pair style provides an efficient implementation that is described in
this paper :ref:`(Lysogorskiy) <Lysogorskiy20211>`.
this paper :ref:`(Lysogorskiy21) <Lysogorskiy20211>`.
In ACE, the total energy is decomposed into a sum over atomic
energies. The energy of atom *i* is expressed as a linear or non-linear
@ -91,7 +91,7 @@ Extrapolation grade
Calculation of extrapolation grade in PACE is implemented in `pair_style
pace/extrapolation`. It is based on the MaxVol algorithm similar to
Moment Tensor Potential (MTP) by Shapeev et al. and is described in
:ref:`(Lysogorskiy2) <Lysogorskiy2022>`. In order to compute
:ref:`(Lysogorskiy23) <Lysogorskiy2023>`. In order to compute
extrapolation grade one needs to provide:
#. ACE potential in B-basis form (`.yaml` format) and
@ -182,12 +182,12 @@ recursive, chunksize = 4096,
.. _Drautz20191:
**(Drautz)** Drautz, Phys Rev B, 99, 014104 (2019).
**(Drautz19)** Drautz, Phys Rev B, 99, 014104 (2019).
.. _Lysogorskiy20211:
**(Lysogorskiy)** Lysogorskiy, van der Oord, Bochkarev, Menon, Rinaldi, Hammerschmidt, Mrovec, Thompson, Csanyi, Ortner, Drautz, npj Comp Mat, 7, 97 (2021).
**(Lysogorskiy21)** Lysogorskiy, van der Oord, Bochkarev, Menon, Rinaldi, Hammerschmidt, Mrovec, Thompson, Csanyi, Ortner, Drautz, npj Comp Mat, 7, 97 (2021).
.. _Lysogorskiy2022:
.. _Lysogorskiy2023:
**(Lysogorskiy2022)** Lysogorskiy, Bochkarev, Mrovec, Drautz, arXiv:2212.08716 (2022).
**(Lysogorskiy23)** Lysogorskiy, Bochkarev, Mrovec, Drautz, Phys Rev Mater, 7, 043801 (2023) / arXiv:2212.08716 (2022).

13
doc/src/pair_smtbq.rst
View File

@ -23,8 +23,9 @@ Description
This pair style computes a variable charge SMTB-Q (Second-Moment
tight-Binding QEq) potential as described in :ref:`SMTB-Q_1 <SMTB-Q_1>` and
:ref:`SMTB-Q_2 <SMTB-Q_2>`. Briefly, the energy of metallic-oxygen systems
is given by three contributions:
:ref:`SMTB-Q_2 <SMTB-Q_2>`.
This potential was first proposed in :ref:`SMTB-Q_0 <SMTB-Q_0>`.
Briefly, the energy of metallic-oxygen systems is given by three contributions:
.. math::
@ -208,7 +209,7 @@ For each cations (metal):
6) Coordination parameter:
* First (:math:`r_{1n}`) and second (:math:`r_{2n}`) neighbor distances
in Angstrom
in angstroms
* Divider line
7) Charge initialization mode:
@ -306,6 +307,12 @@ and R. Tetot, Comput. Mater. Sci. 111 (2016) 181-189
----------
.. _SMTB-Q_0:
**(SMTB-Q_0)** A. Hallil, E. Amzallag, S. Landron, R. Tetot,
Surface Science 605 738-745 (2011);
R. Tetot, A. Hallil, J. Creuze and I. Braems, EPL, 83 40001 (2008)
.. _SMTB-Q_1:
**(SMTB-Q_1)** N. Salles, O. Politano, E. Amzallag, R. Tetot,

4
doc/src/pair_style.rst
View File

@ -132,6 +132,7 @@ accelerated styles exist.
* :doc:`born/coul/msm <pair_born>` - Born with long-range MSM Coulomb
* :doc:`born/coul/wolf <pair_born>` - Born with Wolf potential for Coulomb
* :doc:`born/coul/wolf/cs <pair_cs>` - Born with Wolf potential for Coulomb and core/shell model
* :doc:`born/gauss <pair_born_gauss>` - Born-Mayer / Gaussian potential
* :doc:`bpm/spring <pair_bpm_spring>` - repulsive harmonic force with damping
* :doc:`brownian <pair_brownian>` - Brownian potential for Fast Lubrication Dynamics
* :doc:`brownian/poly <pair_brownian>` - Brownian potential for Fast Lubrication Dynamics with polydispersity
@ -214,6 +215,7 @@ accelerated styles exist.
* :doc:`lennard/mdf <pair_mdf>` - LJ potential in A/B form with a taper function
* :doc:`lepton <pair_lepton>` - pair potential from evaluating a string
* :doc:`lepton/coul <pair_lepton>` - pair potential from evaluating a string with support for charges
* :doc:`lepton/sphere <pair_lepton>` - pair potential from evaluating a string with support for radii
* :doc:`line/lj <pair_line_lj>` - LJ potential between line segments
* :doc:`list <pair_list>` - potential between pairs of atoms explicitly listed in an input file
* :doc:`lj/charmm/coul/charmm <pair_charmm>` - CHARMM potential with cutoff Coulomb
@ -248,12 +250,14 @@ accelerated styles exist.
* :doc:`lj/cut/dipole/cut <pair_dipole>` - point dipoles with cutoff
* :doc:`lj/cut/dipole/long <pair_dipole>` - point dipoles with long-range Ewald
* :doc:`lj/cut/soft <pair_fep_soft>` - LJ with a soft core
* :doc:`lj/cut/sphere <pair_lj_cut_sphere>` - LJ where per-atom radius is used as LJ sigma
* :doc:`lj/cut/thole/long <pair_thole>` - LJ with Coulomb with thole damping
* :doc:`lj/cut/tip4p/cut <pair_lj_cut_tip4p>` - LJ with cutoff Coulomb for TIP4P water
* :doc:`lj/cut/tip4p/long <pair_lj_cut_tip4p>` - LJ with long-range Coulomb for TIP4P water
* :doc:`lj/cut/tip4p/long/soft <pair_fep_soft>` - LJ with cutoff Coulomb for TIP4P water with a soft core
* :doc:`lj/expand <pair_lj_expand>` - Lennard-Jones for variable size particles
* :doc:`lj/expand/coul/long <pair_lj_expand>` - Lennard-Jones for variable size particles with long-range Coulomb
* :doc:`lj/expand/sphere <pair_lj_expand_sphere>` - Variable size LJ where per-atom radius is used as delta (size)
* :doc:`lj/gromacs <pair_gromacs>` - GROMACS-style Lennard-Jones potential
* :doc:`lj/gromacs/coul/gromacs <pair_gromacs>` - GROMACS-style LJ and Coulomb potential
* :doc:`lj/long/coul/long <pair_lj_long>` - long-range LJ and long-range Coulomb

40
doc/src/print.rst
View File

@ -46,6 +46,20 @@ lines of output, the string can be enclosed in triple quotes, as in
the last example above. If the text string contains variables, they
will be evaluated and their current values printed.
.. versionadded:: TBD
support for vector style variables
See the :doc:`variable <variable>` command for a description of
*equal* and *vector* style variables which are typically the most
useful ones to use with the print command. Equal- and vector-style
variables can calculate formulas involving mathematical operations,
atom properties, group properties, thermodynamic properties, global
values calculated by a :doc:`compute <compute>` or :doc:`fix <fix>`,
or references to other :doc:`variables <variable>`. Vector-style
variables are printed in a bracketed, comma-separated format,
e.g. [1,2,3,4] or [12.5,2,4.6,10.1].
.. note::
As discussed on the :doc:`Commands parse <Commands_parse>` doc
@ -60,6 +74,15 @@ will be evaluated and their current values printed.
This is also explained on the :doc:`Commands parse
<Commands_parse>` doc page.
If you want the print command to be executed multiple times (with
changing variable values), there are 3 options. First, consider using
the :doc:`fix print <fix_print>` command, which will print a string
periodically during a simulation. Second, the print command can be
used as an argument to the *every* option of the :doc:`run <run>`
command. Third, the print command could appear in a section of the
input script that is looped over (see the :doc:`jump <jump>` and
:doc:`next <next>` commands).
If the *file* or *append* keyword is used, a filename is specified to
which the output will be written. If *file* is used, then the
filename is overwritten if it already exists. If *append* is used,
@ -74,23 +97,6 @@ logfile can be turned on or off as desired. In multi-partition
calculations, the *screen* option and the corresponding output only
apply to the screen and logfile of the individual partition.
If you want the print command to be executed multiple times (with
changing variable values), there are 3 options. First, consider using
the :doc:`fix print <fix_print>` command, which will print a string
periodically during a simulation. Second, the print command can be
used as an argument to the *every* option of the :doc:`run <run>`
command. Third, the print command could appear in a section of the
input script that is looped over (see the :doc:`jump <jump>` and
:doc:`next <next>` commands).
See the :doc:`variable <variable>` command for a description of *equal*
style variables which are typically the most useful ones to use with
the print command. Equal-style variables can calculate formulas
involving mathematical operations, atom properties, group properties,
thermodynamic properties, global values calculated by a
:doc:`compute <compute>` or :doc:`fix <fix>`, or references to other
:doc:`variables <variable>`.
Restrictions
""""""""""""
none

2
doc/src/read_dump.rst
View File

@ -132,7 +132,7 @@ files can be written by LAMMPS via the :doc:`dump dcd <dump>` command.
The *path* value specifies a list of directories which LAMMPS will
search for the molfile plugins appropriate to the specified *style*\ .
The syntax of the *path* value is like other search paths: it can
contain multiple directories separated by a colon (or semi-colon on
contain multiple directories separated by a colon (or semicolon on
windows). The *path* keyword is optional and defaults to ".",
i.e. the current directory.

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