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

Merge branch 'lammps:develop' into improve_type_label_support

Browse Source
This commit is contained in:
Jacob Gissinger
2024-06-13 19:26:42 -04:00
committed by GitHub
parent 61b8619f07 7ef9a93a75
commit 11ef510a93
269 changed files with 4343 additions and 30611 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/src/Commands_bond.rst
View File

@ -72,7 +72,7 @@ OPT.
* :doc:`none <angle_none>`
* :doc:`zero <angle_zero>`
* :doc:`hybrid <angle_hybrid>`
* :doc:`hybrid (k) <angle_hybrid>`
*
*
*

8
doc/src/Commands_removed.rst
View File

@ -148,6 +148,14 @@ performance characteristics on NVIDIA GPUs. Both, the KOKKOS
and the :ref:`GPU package <PKG-GPU>` are maintained
and allow running LAMMPS with GPU acceleration.
i-PI tool
---------
.. versionchanged:: TBD
The i-PI tool has been removed from the LAMMPS distribution. Instead,
instructions to install i-PI from PyPi via pip are provided.
restart2data tool
-----------------

2
doc/src/Fortran.rst
View File

@ -305,6 +305,8 @@ of the contents of the :f:mod:`LIBLAMMPS` Fortran interface to LAMMPS.
:ftype extract_setting: function
:f extract_global: :f:func:`extract_global`
:ftype extract_global: function
:f map_atom: :f:func:`map_atom`
:ftype map_atom: function
:f extract_atom: :f:func:`extract_atom`
:ftype extract_atom: function
:f extract_compute: :f:func:`extract_compute`

9
doc/src/Howto_bpm.rst
View File

@ -15,7 +15,8 @@ orientation for rotational models. This produces a stress-free initial
state. Furthermore, bonds are allowed to break under large strains,
producing fracture. The examples/bpm directory has sample input scripts
for simulations of the fragmentation of an impacted plate and the
pouring of extended, elastic bodies.
pouring of extended, elastic bodies. See :ref:`(Clemmer) <howto-Clemmer>`
for more general information on the approach and the LAMMPS implementation.
----------
@ -150,3 +151,9 @@ the following are currently compatible with BPM bond styles:
interactions, one will need to switch between different *special_bonds*
settings in the input script. An example is found in
``examples/bpm/impact``.
----------
.. _howto-Clemmer:
**(Clemmer)** Clemmer, Monti, Lechman, Soft Matter, 20, 1702 (2024).

6
doc/src/Library_properties.rst
View File

@ -13,6 +13,7 @@ This section documents the following functions:
- :cpp:func:`lammps_extract_setting`
- :cpp:func:`lammps_extract_global_datatype`
- :cpp:func:`lammps_extract_global`
- :cpp:func:`lammps_map_atom`
--------------------
@ -120,3 +121,8 @@ subdomains and processors.
.. doxygenfunction:: lammps_extract_global
:project: progguide
-----------------------
.. doxygenfunction:: lammps_map_atom
:project: progguide

37
doc/src/Tools.rst
View File

@ -90,7 +90,7 @@ Miscellaneous tools
* :ref:`LAMMPS coding standards <coding_standard>`
* :ref:`emacs <emacs>`
* :ref:`i-pi <ipi>`
* :ref:`i-PI <ipi>`
* :ref:`kate <kate>`
* :ref:`LAMMPS shell <lammps_shell>`
* :ref:`LAMMPS GUI <lammps_gui>`
@ -376,21 +376,40 @@ See README file in the tools/fep directory.
.. _ipi:
i-pi tool
i-PI tool
-------------------
The tools/i-pi directory contains a version of the i-PI package, with
all the LAMMPS-unrelated files removed. It is provided so that it can
be used with the :doc:`fix ipi <fix_ipi>` command to perform
path-integral molecular dynamics (PIMD).
.. versionchanged:: TBD
The tools/i-pi directory used to contain a bundled version of the i-PI
software package for use with LAMMPS. This version, however, was
removed in 06/2024.
The i-PI package was created and is maintained by Michele Ceriotti,
michele.ceriotti at gmail.com, to interface to a variety of molecular
dynamics codes.
See the tools/i-pi/manual.pdf file for an overview of i-PI, and the
:doc:`fix ipi <fix_ipi>` page for further details on running PIMD
calculations with LAMMPS.
i-PI is now available via PyPi using the pip package manager at:
https://pypi.org/project/ipi/
Here are the commands to set up a virtual environment and install
i-PI into it with all its dependencies.
.. code-block:: sh
python -m venv ipienv
source ipienv/bin/activate
pip install --upgrade pip
pip install ipi
To install the development version from GitHub, please use:
.. code-block:: sh
pip install git+https://github.com/i-pi/i-pi.git
For further information, please consult the [i-PI home
page](https://ipi-code.org).
----------

9
doc/src/bond_hybrid.rst
View File

@ -1,8 +1,11 @@
.. index:: bond_style hybrid
.. index:: bond_style hybrid/kk
bond_style hybrid command
=========================
Accelerator Variants: *hybrid/kk*
Syntax
""""""
@ -15,7 +18,7 @@ Syntax
Examples
""""""""
.. code-block: LAMMPS
.. code-block:: LAMMPS
bond_style hybrid harmonic fene
bond_coeff 1 harmonic 80.0 1.2
@ -60,6 +63,10 @@ bond types.
----------
.. include:: accel_styles.rst
----------
Restrictions
""""""""""""

38
doc/src/compute_count_type.rst
View File

@ -12,7 +12,7 @@ Syntax
* 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}
* mode = *atom* or *bond* or *angle* or *dihedral* or *improper*
Examples
""""""""
@ -69,29 +69,42 @@ for each type:
----------
If the {mode} setting is {atom} then the count of atoms for each atom
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
The atom count for each type can be normalized by the total number of
atoms like so:
.. code-block:: LAMMPS
compute typevec all count/type atom # number of atoms of each type
variable normtypes vector c_typevec/atoms # divide by total number of atoms
variable ntypes equal extract_setting(ntypes) # number of atom types
thermo_style custom step v_normtypes[*${ntypes}] # vector variable needs upper limit
Similarly, bond counts can be normalized by the total number of bonds.
The same goes for angles, dihedrals, and impropers (see below).
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
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.
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
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
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
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.
@ -101,18 +114,19 @@ 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
*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
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".
The scalar and vector values calculated by this compute are both
"intensive".
Restrictions
""""""""""""

2
doc/src/compute_stress_mop.rst
View File

@ -126,7 +126,7 @@ These styles are part of the EXTRA-COMPUTE package. They are only
enabled if LAMMPS is built with that package. See the :doc:`Build
package <Build_package>` doc page on for more info.
The method is only implemented for 3d orthogonal simulation boxes whose
The method is implemented for orthogonal simulation boxes whose
size does not change in time, and axis-aligned planes.
The method only works with two-body pair interactions, because it

13
doc/src/create_atoms.rst
View File

@ -475,12 +475,13 @@ to.
The *overlap* keyword only applies to the *random* style. It prevents
newly created particles from being created closer than the specified
*Doverlap* distance from any other particle. When the particles being
created are molecules, the radius of the molecule (from its geometric
center) is added to *Doverlap*. If particles have finite size (see
:doc:`atom_style sphere <atom_style>` for example) *Doverlap* should
be specified large enough to include the particle size in the
non-overlapping criterion.
*Doverlap* distance from any other particle. If particles have finite
size (see :doc:`atom_style sphere <atom_style>` for example) *Doverlap*
should be specified large enough to include the particle size in the
non-overlapping criterion. If molecules are being randomly inserted, then
an insertion is only accepted if each particle in the molecule meets the
overlap criterion with respect to other particles (not including particles
in the molecule itself).
.. note::

2
doc/src/fix_atom_swap.rst
View File

@ -168,7 +168,7 @@ the following global cumulative quantities:
* 1 = swap attempts
* 2 = swap accepts
The vector values calculated by this fix are "extensive".
The vector values calculated by this fix are "intensive".
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

23
doc/src/fix_deform_pressure.rst
View File

@ -29,10 +29,12 @@ Syntax
NOTE: All other styles are documented by the :doc:`fix deform <fix_deform>` command
*xy*, *xz*, *yz* args = style value
style = *final* or *delta* or *vel* or *erate* or *trate* or *wiggle* or *variable* or *pressure*
style = *final* or *delta* or *vel* or *erate* or *trate* or *wiggle* or *variable* or *pressure* or *erate/rescale*
*pressure* values = target gain
target = target pressure (pressure units)
gain = proportional gain constant (1/(time * pressure) or 1/time units)
*erate/rescale* value = R
R = engineering shear strain rate (1/time units)
NOTE: All other styles are documented by the :doc:`fix deform <fix_deform>` command
*box* = style value
@ -159,6 +161,21 @@ details of a simulation and testing different values is
recommended. One can also apply a maximum limit to the magnitude of
the applied strain using the :ref:`max/rate <deform_max_rate>` option.
The *erate/rescale* style operates similarly to the *erate* style with
a specified strain rate in units of 1/time. The difference is that
the change in the tilt factor will depend on the current length of
the box perpendicular to the shear direction, L, instead of the
original length, L0. The tilt factor T as a function of time will
change as
.. parsed-literal::
T(t) = T(t-1) + L\*erate\* \Delta t
where T(t-1) is the tilt factor on the previous timestep and :math:`\Delta t`
is the timestep size. This option may be useful in scenarios where
L changes in time.
----------
The *box* parameter provides an additional control over the *x*, *y*,
@ -294,6 +311,10 @@ This fix is not invoked during :doc:`energy minimization <minimize>`.
Restrictions
""""""""""""
This fix is part of the EXTRA-FIX package. It is only enabled if LAMMPS
was built with that package. See the :doc:`Build package <Build_package>`
page for more info.
You cannot apply x, y, or z deformations to a dimension that is
shrink-wrapped via the :doc:`boundary <boundary>` command.

2
doc/src/fix_gcmc.rst
View File

@ -422,7 +422,7 @@ the following global cumulative quantities:
* 7 = rotation attempts
* 8 = rotation successes
The vector values calculated by this fix are "extensive".
The vector values calculated by this fix are "intensive".
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

3
doc/src/fix_hyper_local.rst
View File

@ -512,8 +512,7 @@ Value 27 computes the average boost for biased bonds only on this step.
Value 28 is the count of bonds with an absolute value of strain >= q
on this step.
The scalar value is an "extensive" quantity since it grows with the
system size; the vector values are all "intensive".
The scalar value and vector values are all "intensive".
This fix also computes a local vector of length the number of bonds
currently in the system. The value for each bond is its :math:`C_{ij}`

54
doc/src/fix_ipi.rst
View File

@ -35,23 +35,24 @@ Description
"""""""""""
This fix enables LAMMPS to be run as a client for the i-PI Python
wrapper :ref:`(IPI) <ipihome>` for performing a path integral molecular dynamics
(PIMD) simulation. The philosophy behind i-PI is described in the
following publication :ref:`(IPI-CPC) <IPICPC>`.
wrapper :ref:`(IPI) <ipihome>`. i-PI is a universal force engine,
designed to perform advanced molecular simulations, with a special
focus on path integral molecular dynamics (PIMD) simulation.
The philosophy behind i-PI is to separate the evaluation of the
energy and forces, which is delegated to the client, and the evolution
of the dynamics, that is the responsibility of i-PI. This approach also
simplifies combining energies computed from different codes, which
can for instance be useful to mix first-principles calculations,
empirical force fields or machine-learning potentials.
The following publication :ref:`(IPI-CPC-2014) <IPICPC>` discusses the
overall implementation of i-PI, and focuses on path-integral techniques,
while a later release :ref:`(IPI-CPC-2019) <IPICPC2>` introduces several
additional features and simulation schemes.
A version of the i-PI package, containing only files needed for use
with LAMMPS, is provided in the tools/i-pi directory. See the
tools/i-pi/manual.pdf for an introduction to i-PI. The
examples/PACKAGES/i-pi directory contains example scripts for using i-PI
with LAMMPS.
In brief, the path integral molecular dynamics is performed by the
Python wrapper, while the client (LAMMPS in this case) simply computes
forces and energy for each configuration. The communication between
the two components takes place using sockets, and is reduced to the
bare minimum. All the parameters of the dynamics are specified in the
input of i-PI, and all the parameters of the force field must be
specified as LAMMPS inputs, preceding the *fix ipi* command.
The communication between i-PI and LAMMPS takes place using sockets,
and is reduced to the bare minimum. All the parameters of the dynamics
are specified in the input of i-PI, and all the parameters of the force
field must be specified as LAMMPS inputs, preceding the *fix ipi* command.
The server address must be specified by the *address* argument, and
can be either the IP address, the fully-qualified name of the server,
@ -75,6 +76,20 @@ If the cell varies too wildly, it may be advisable to re-initialize
these interactions at each call. This behavior can be requested by
setting the *reset* switch.
Obtaining i-PI
""""""""""""""
Here are the commands to set up a virtual environment and install
i-PI into it with all its dependencies via the PyPi repository and
the pip package manager.
.. code-block:: sh
python -m venv ipienv
source ipienv/bin/activate
pip install --upgrade pip
pip install ipi
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
@ -111,9 +126,14 @@ Related commands
.. _IPICPC:
**(IPI-CPC)** Ceriotti, More and Manolopoulos, Comp Phys Comm, 185,
**(IPI-CPC-2014)** Ceriotti, More and Manolopoulos, Comp Phys Comm 185,
1019-1026 (2014).
.. _IPICPC2:
**(IPI-CPC-2019)** Kapil et al., Comp Phys Comm 236, 214-223 (2019).
.. _ipihome:
**(IPI)**

2
doc/src/fix_mol_swap.rst
View File

@ -149,7 +149,7 @@ the following global cumulative quantities:
* 1 = swap attempts
* 2 = swap accepts
The vector values calculated by this fix are "extensive".
The vector values calculated by this fix are "intensive".
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

15
doc/src/fix_nonaffine_displacement.rst
View File

@ -8,7 +8,7 @@ Syntax
.. parsed-literal::
fix ID group nonaffine/displacement style args reference/style nstep
fix ID group nonaffine/displacement style args reference/style nstep keyword values
* ID, group are documented in :doc:`fix <fix>` command
* nonaffine/displacement = style name of this fix command
@ -32,6 +32,13 @@ Syntax
*update* = update the reference frame every *nstep* timesteps
*offset* = update the reference frame *nstep* timesteps before calculating the nonaffine displacement
* zero or more keyword/value pairs may be appended
.. parsed-literal::
*z/min* values = zmin
zmin = minimum coordination number to calculate D2min
Examples
""""""""
@ -76,6 +83,12 @@ is the identity tensor. This calculation is only performed on timesteps that
are a multiple of *nevery* (including timestep zero). Data accessed before
this occurs will simply be zeroed.
For particles with low coordination numbers, calculations of :math:`D^2_\mathrm{min}`
may not be accurate. An optional minimum coordination number can be defined using
the *z/min* keyword. If any particle has fewer than the specified number of particles
in the cutoff distance or in contact, the above calculations will be skipped and the
corresponding peratom array entries will be zero.
The *integrated* style simply integrates the velocity of particles
every timestep to calculate a displacement. This style only works if
used in conjunction with another fix that deforms the box and displaces

74
doc/src/fix_reaxff_species.rst
View File

@ -20,7 +20,7 @@ Syntax
* Nfreq = calculate average bond-order every this many timesteps
* filename = name of output file
* zero or more keyword/value pairs may be appended
* keyword = *cutoff* or *element* or *position* or *delete*
* keyword = *cutoff* or *element* or *position* or *delete* or *delete_rate_limit*
.. parsed-literal::
@ -110,10 +110,10 @@ all types from 1 to :math:`N`. A leading asterisk means all types from
The optional keyword *element* can be used to specify the chemical
symbol printed for each LAMMPS atom type. The number of symbols must
match the number of LAMMPS atom types and each symbol must consist of
1 or 2 alphanumeric characters. Normally, these symbols should be
chosen to match the chemical identity of each LAMMPS atom type, as
specified using the :doc:`reaxff pair_coeff <pair_reaxff>` command and
the ReaxFF force field file.
1 or 2 alphanumeric characters. By default, these symbols are the same
as the chemical identity of each LAMMPS atom type, as specified by the
:doc:`ReaxFF pair_coeff <pair_reaxff>` command and the ReaxFF force
field file.
The optional keyword *position* writes center-of-mass positions of
each identified molecules to file *filepos* every *posfreq* timesteps.
@ -134,36 +134,34 @@ value. For example, AuO.pos.\* becomes AuO.pos.0, AuO.pos.1000, etc.
.. versionadded:: 3Aug2022
The optional keyword *delete* enables the periodic removal of
molecules from the system. Criteria for deletion can be either a list
of specific chemical formulae or a range of molecular weights.
Molecules are deleted every *Nfreq* timesteps, and bond connectivity
is determined using the *Nevery* and *Nrepeat* keywords. The
*filedel* argument is the name of the output file that records the
species that are removed from the system. The *specieslist* keyword
permits specific chemical species to be deleted. The *Nspecies*
argument specifies how many species are eligible for deletion and is
followed by a list of chemical formulae, whose strings are compared to
species identified by this fix. For example, "specieslist 2 CO CO2"
deletes molecules that are identified as "CO" and "CO2" in the species
output file. When using the *specieslist* keyword, the *filedel* file
has the following format: the first line lists the chemical formulae
eligible for deletion, and each additional line contains the timestep
on which a molecule deletion occurs and the number of each species
deleted on that timestep. The *masslimit* keyword permits deletion of
molecules with molecular weights between *massmin* and *massmax*.
When using the *masslimit* keyword, each line of the *filedel* file
contains the timestep on which deletions occurs, followed by how many
of each species are deleted (with quantities preceding chemical
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. 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).
The optional keyword *delete* enables the periodic removal of molecules
from the system :ref:`(Gissinger) <Delete>`. Criteria for deletion can
be either a list of specific chemical formulae or a range of molecular
weights. Molecules are deleted every *Nfreq* timesteps, and bond
connectivity is determined using the *Nevery* and *Nrepeat* keywords. The
*filedel* argument is the name of the output file that records the species
that are removed from the system. The *specieslist* keyword permits
specific chemical species to be deleted. The *Nspecies* argument specifies
how many species are eligible for deletion and is followed by a list of
chemical formulae, whose strings are compared to species identified by this
fix. For example, "specieslist 2 CO CO2" deletes molecules that are
identified as "CO" and "CO2" in the species output file. When using the
*specieslist* keyword, the *filedel* file has the following format: the
first line lists the chemical formulae eligible for deletion, and each
additional line contains the timestep on which a molecule deletion occurs
and the number of each species deleted on that timestep. The *masslimit*
keyword permits deletion of molecules with molecular weights between
*massmin* and *massmax*. When using the *masslimit* keyword, each line of
the *filedel* file contains the timestep on which deletions occurs,
followed by how many of each species are deleted (with quantities preceding
chemical 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. 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).
----------
@ -233,5 +231,9 @@ Default
"""""""
The default values for bond-order cutoffs are 0.3 for all I-J pairs.
The default element symbols are C, H, O, N.
The default element symbols are taken from the ReaxFF pair_coeff command.
Position files are not written by default.
.. _Delete:
**(Gissinger)** Jacob R. Gissinger, Scott R. Zavada, Joseph G. Smith, Josh Kemppainen, Ivan Gallegos, Gregory M. Odegard, Emilie J. Siochi, and Kristopher E. Wise, Carbon, 202, 336-347 (2023).

2
doc/src/fix_sgcmc.rst
View File

@ -148,6 +148,8 @@ components of the vector represent the following quantities:
* ...
* N+2: The current global concentration of species *X* (= number of atoms of type *N* / total number of atoms)
The vector values calculated by this fix are "intensive".
Restrictions
""""""""""""

2
doc/src/fix_widom.rst
View File

@ -182,7 +182,7 @@ the following global cumulative quantities:
* 2 = average difference in potential energy on each timestep
* 3 = volume of the insertion region
The vector values calculated by this fix are "extensive".
The vector values calculated by this fix are "intensive".
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

4
doc/src/improper_cossq.rst
View File

@ -64,8 +64,8 @@ Restrictions
""""""""""""
This improper style can only be used if LAMMPS was built with the
MOLECULE package. See the :doc:`Build package <Build_package>` doc
page for more info.
EXTRA-MOLECULE package. See the :doc:`Build package <Build_package>`
doc page for more info.
Related commands
""""""""""""""""

4
doc/src/improper_distance.rst
View File

@ -54,8 +54,8 @@ Restrictions
""""""""""""
This improper style can only be used if LAMMPS was built with the
MOLECULE package. See the :doc:`Build package <Build_package>` doc
page for more info.
EXTRA-MOLECULE package. See the :doc:`Build package <Build_package>`
doc page for more info.
Related commands
""""""""""""""""

4
doc/src/improper_fourier.rst
View File

@ -60,8 +60,8 @@ Restrictions
""""""""""""
This angle style can only be used if LAMMPS was built with the
MOLECULE package. See the :doc:`Build package <Build_package>` doc
page for more info.
EXTRA-MOLECULE package. See the :doc:`Build package <Build_package>`
doc page for more info.
Related commands
""""""""""""""""

4
doc/src/improper_ring.rst
View File

@ -72,8 +72,8 @@ Restrictions
""""""""""""
This improper style can only be used if LAMMPS was built with the
MOLECULE package. See the :doc:`Build package <Build_package>` doc
page for more info.
EXTRA-MOLECULE package. See the :doc:`Build package <Build_package>`
doc page for more info.
Related commands
""""""""""""""""

9
doc/src/pair_coul.rst
View File

@ -379,10 +379,11 @@ These pair styles can only be used via the *pair* keyword of the
Restrictions
""""""""""""
The *coul/cut/global*, *coul/long*, *coul/msm*, *coul/streitz*, and *tip4p/long* styles
are part of the KSPACE package. They are only enabled if LAMMPS was built
with that package. See the :doc:`Build package <Build_package>` doc page
for more info.
The *coul/long*, *coul/msm*, *coul/streitz*, and *tip4p/long* styles are
part of the KSPACE package. The *coul/cut/global* and *coul/exclude* are
part of the EXTRA-PAIR package. A pair style is only enabled if LAMMPS was
built with its corresponding package. See the :doc:`Build package <Build_package>`
doc page for more info.
Related commands
""""""""""""""""

24
doc/src/pair_granular.rst
View File

@ -187,6 +187,7 @@ for the damping model currently supported are:
2. *mass_velocity*
3. *viscoelastic*
4. *tsuji*
5. *coeff_restitution*
If the *damping* keyword is not specified, the *viscoelastic* model is
used by default.
@ -248,6 +249,29 @@ The dimensionless coefficient of restitution :math:`e` specified as part
of the normal contact model parameters should be between 0 and 1, but
no error check is performed on this.
The *coeff_restitution* model is useful when a specific normal coefficient of
restitution :math:`e` is required. In these models, the normal coefficient of
restitution :math:`e` is specified as an input. Following the approach of
:ref:`(Brilliantov et al) <Brill1996>`, when using the *hooke* normal model,
*coeff_restitution* calculates the damping coefficient as:
.. math::
\eta_n = \sqrt{\frac{4m_{eff}k_n}{1+\left( \frac{\pi}{\log(e)}\right)^2}} ,
For any other normal model, e.g. the *hertz* and *hertz/material* models, the damping
coefficient is:
.. math::
\eta_n = -2\sqrt{\frac{5}{6}}\frac{\log(e)}{\sqrt{\pi^2+(\log(e))^2}}(R_{eff} \delta_{ij})^{\frac{1}{4}}\sqrt{\frac{3}{2}k_n m_{eff}} ,
where :math:`k_n = \frac{4}{3} E_{eff}` for the *hertz/material* model. Since
*coeff_restitution* accounts for the effective mass, effective radius, and
pairwise overlaps (except when used with the *hooke* normal model) when calculating
the damping coefficient, it accurately reproduces the specified coefficient of
restitution for both monodisperse and polydisperse particle pairs.
The total normal force is computed as the sum of the elastic and
damping components:

169
doc/src/replicate.rst
View File

@ -8,56 +8,118 @@ Syntax
.. code-block:: LAMMPS
replicate nx ny nz *keyword*
replicate nx ny nz keyword ...
nx,ny,nz = replication factors in each dimension
* optional *keyword* = *bbox*
* zero or more keywords may be appended
* keyword = *bbox* or *bond/periodic*
.. parsed-literal::
*bbox* = only check atoms in replicas that overlap with a processor's subdomain
*bbox* = use a bounding-box algorithm which is faster for large proc counts
*bond/periodic* = use an algorithm that correctly replicates periodic bond loops
Examples
""""""""
For examples of replicating simple linear polymer chains (periodic or
non-periodic) or periodic carbon nanotubes, see examples/replicate.
.. code-block:: LAMMPS
replicate 2 3 2
replicate 2 3 2 bbox
replicate 2 3 2 bond/periodic
Description
"""""""""""
Replicate the current simulation one or more times in each dimension.
For example, replication factors of 2,2,2 will create a simulation
with 8x as many atoms by doubling the simulation domain in each
dimension. A replication factor of 1 in a dimension leaves the
simulation domain unchanged. When the new simulation box is created
it is also partitioned into a regular 3d grid of rectangular bricks,
one per processor, based on the number of processors being used and
the settings of the :doc:`processors <processors>` command. The
partitioning can later be changed by the :doc:`balance <balance>` or
:doc:`fix balance <fix_balance>` commands.
Replicate the current system one or more times in each dimension. For
example, replication factors of 2,2,2 will create a simulation with 8x
as many atoms by doubling the size of the simulation box in each
dimension. A replication factor of 1 leaves the simulation domain
unchanged in that dimension.
All properties of the atoms are replicated, including their
velocities, which may or may not be desirable. New atom IDs are
assigned to new atoms, as are molecule IDs. Bonds and other topology
interactions are created between pairs of new atoms as well as between
old and new atoms. This is done by using the image flag for each atom
to "unwrap" it out of the periodic box before replicating it.
When the new simulation box is created it is partitioned into a
regular 3d grid of rectangular bricks, one per processor, based on the
number of processors being used and the settings of the
:doc:`processors <processors>` command. The partitioning can be
changed by subsequent :doc:`balance <balance>` or :doc:`fix balance
<fix_balance>` commands.
This means that any molecular bond you specify in the original data
file that crosses a periodic boundary should be between two atoms with
image flags that differ by 1. This will allow the bond to be
unwrapped appropriately.
All properties of each atom are replicated (except per-atom fix data,
see the Restrictions section below). This includes their velocities,
which may or may not be desirable. New atom IDs are assigned to new
atoms, as are new molecule IDs. Bonds and other topology interactions
are created between pairs of new atoms as well as between old and new
atoms.
The optional keyword *bbox* uses a bounding box to only check atoms in
replicas that overlap with a processor's subdomain when assigning
atoms to processors. It typically results in a substantial speedup
when using the replicate command on a large number of processors. It
does require temporary use of more memory, specifically that each
processor can store all atoms in the entire system before it is
replicated.
.. note::
The bond discussion which follows only refers to models with
permanent covalent bonds typically defined in LAMMPS via a data
file. It is not relevant to systems modeled with many-body
potentials which can define bonds on-the-fly, based on the current
positions of nearby atoms, e.g. models using the :doc:`AIREBO
<pair_airebo>` or :doc:`ReaxFF <pair_reaxff>` potentials.
If the *bond/periodic* keyword is not specified, bond replication is
done by using the image flag for each atom to "unwrap" it out of the
periodic box before replicating it. After replication is performed,
atoms outside the new periodic box are wrapped back into it. This
assigns correct images flags to all atoms in the system. For this to
work, all original atoms in the original simulation box must have
consistent image flags. This means that if two atoms have a bond
between them which crosses a periodic boundary, their respective image
flags will differ by 1 in that dimension.
Image flag consistency is not possible if a system has a periodic bond
loop, meaning there is a chain of bonds which crosses an entire
dimension and re-connects to itself across a periodic boundary. In
this case you MUST use the *bond/periodic* keyword to correctly
replicate the system. This option zeroes the image flags for all
atoms and uses a different algorithm to find new (nearby) bond
neighbors in the replicated system. In the final replicated system
all image flags are zero (in each dimension).
.. note::
LAMMPS does not check for image flag consistency before performing
the replication (it does issue a warning about this before a
simulation is run). If the original image flags are inconsistent,
the replicated system will also have inconsistent image flags, but
will otherwise be correctly replicated. This is NOT the case if
there is a periodic bond loop. See the next note.
.. note::
LAMMPS does not check for periodic bond loops. If you use the
*bond/periodic* keyword for a system without periodic bond loops,
the system will be correctly replicated, but image flag information
will be lost (which may or may not be important to your model). If
you do not use the *bond/periodic* keyword for a system with
periodic bond loops, the replicated system will have invalid bonds
(typically very long), resulting in bad dynamics.
If possible, the *bbox* keyword should be used when running on a large
number of processors, as it can result in a substantial speed-up for
the replication operation. It uses a bounding box to only check atoms
in replicas that overlap with each processor's new subdomain when
assigning atoms to processors. It also preserves image flag
information. The only drawback to the *bbox* option is that it
requires a temporary use of more memory. Each processor must be able
to store all atoms (and their per-atom data) in the original system,
before it is replicated.
.. note::
The algorithm used by the *bond/periodic* keyword builds on the
algorithm used by the *bbox* keyword and thus has the same memory
requirements. If you specify only the *bond/peridoic* keyword it
will internally set the *bbox* keyword as well.
----------
Restrictions
""""""""""""
@ -65,49 +127,30 @@ Restrictions
A 2d simulation cannot be replicated in the z dimension.
If a simulation is non-periodic in a dimension, care should be used
when replicating it in that dimension, as it may put atoms nearly on
top of each other.
.. note::
You cannot use the replicate command on a system which has a
molecule that spans the box and is bonded to itself across a periodic
boundary, so that the molecule is effectively a loop. A simple
example would be a linear polymer chain that spans the simulation box
and bonds back to itself across the periodic boundary. More realistic
examples would be a CNT (meant to be an infinitely long CNT) or a
graphene sheet or a bulk periodic crystal where there are explicit
bonds specified between near neighbors. (Note that this only applies
to systems that have permanent bonds as specified in the data file. A
CNT that is just atoms modeled with the :doc:`AIREBO potential <pair_airebo>` has no such permanent bonds, so it can be
replicated.) The reason replication does not work with those systems
is that the image flag settings described above cannot be made
consistent. I.e. it is not possible to define images flags so that
when every pair of bonded atoms is unwrapped (using the image flags),
they will be close to each other. The only way the replicate command
could work in this scenario is for it to break a bond, insert more
atoms, and re-connect the loop for the larger simulation box. But it
is not clever enough to do this. So you will have to construct a
larger version of your molecule as a pre-processing step and input a
new data file to LAMMPS.
when replicating it in that dimension, as it may generate atoms nearly
on top of each other.
If the current simulation was read in from a restart file (before a
run is performed), there must not be any fix information stored in
the file for individual atoms. Similarly, no fixes can be defined at
the time the replicate command is used that require vectors of atom
run is performed), there must not be any fix information stored in the
file for individual atoms. Similarly, no fixes can be defined at the
time the replicate command is used that require vectors of atom
information to be stored. This is because the replicate command does
not know how to replicate that information for new atoms it creates.
To work around this restriction, restart files may be converted into
data files and fixes may be undefined via the :doc:`unfix <unfix>`
command before and redefined after the replicate command.
To work around this restriction two options are possible. (1) Fixes
which use the stored data in the restart file can be defined before
replication and then deleted via the :doc:`unfix <unfix>` command and
re-defined after it. Or (2) the restart file can be converted to a
data file (which deletes the stored fix information) and fixes defined
after the replicate command. In both these scenarios, the per-atom
fix information in the restart file is lost.
Related commands
""""""""""""""""
none
Default
"""""""
none
No settings for using the *bbox* or *bond/periodic* algorithms.

46
doc/src/variable.rst
View File

@ -67,7 +67,7 @@ Syntax
bound(group,dir,region), gyration(group,region), ke(group,reigon),
angmom(group,dim,region), torque(group,dim,region),
inertia(group,dimdim,region), omega(group,dim,region)
special functions = sum(x), min(x), max(x), ave(x), trap(x), slope(x), gmask(x), rmask(x), grmask(x,y), next(x), is_file(name), is_os(name), extract_setting(name), label2type(kind,label), is_typelabel(kind,label)
special functions = sum(x), min(x), max(x), ave(x), trap(x), slope(x), sort(x), rsort(x), gmask(x), rmask(x), grmask(x,y), next(x), is_file(name), is_os(name), extract_setting(name), label2type(kind,label), is_typelabel(kind,label)
feature functions = is_available(category,feature), is_active(category,feature), is_defined(category,id)
atom value = id[i], mass[i], type[i], mol[i], x[i], y[i], z[i], vx[i], vy[i], vz[i], fx[i], fy[i], fz[i], q[i]
atom vector = id, mass, type, mol, radius, q, x, y, z, vx, vy, vz, fx, fy, fz
@ -547,7 +547,7 @@ variables.
+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Region functions | count(ID,IDR), mass(ID,IDR), charge(ID,IDR), xcm(ID,dim,IDR), vcm(ID,dim,IDR), fcm(ID,dim,IDR), bound(ID,dir,IDR), gyration(ID,IDR), ke(ID,IDR), angmom(ID,dim,IDR), torque(ID,dim,IDR), inertia(ID,dimdim,IDR), omega(ID,dim,IDR) |
+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Special functions | sum(x), min(x), max(x), ave(x), trap(x), slope(x), gmask(x), rmask(x), grmask(x,y), next(x), is_file(name), is_os(name), extract_setting(name), label2type(kind,label), is_typelabel(kind,label) |
| Special functions | sum(x), min(x), max(x), ave(x), trap(x), slope(x), sort(x), rsort(x), gmask(x), rmask(x), grmask(x,y), next(x), is_file(name), is_os(name), extract_setting(name), label2type(kind,label), is_typelabel(kind,label) |
+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Feature functions | is_available(category,feature), is_active(category,feature), is_defined(category,id) |
+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@ -913,23 +913,27 @@ Special Functions
Special functions take specific kinds of arguments, meaning their
arguments cannot be formulas themselves.
The sum(x), min(x), max(x), ave(x), trap(x), and slope(x) functions
each take 1 argument which is of the form "c_ID" or "c_ID[N]" or
"f_ID" or "f_ID[N]" or "v_name". The first two are computes and the
second two are fixes; the ID in the reference should be replaced by
the ID of a compute or fix defined elsewhere in the input script. The
compute or fix must produce either a global vector or array. If it
produces a global vector, then the notation without "[N]" should be
used. If it produces a global array, then the notation with "[N]"
should be used, when N is an integer, to specify which column of the
global array is being referenced. The last form of argument "v_name"
is for a vector-style variable where "name" is replaced by the name of
the variable.
The sum(x), min(x), max(x), ave(x), trap(x), slope(x), sort(x), and
rsort(x) functions each take 1 argument which is of the form "c_ID" or
"c_ID[N]" or "f_ID" or "f_ID[N]" or "v_name". The first two are
computes and the second two are fixes; the ID in the reference should be
replaced by the ID of a compute or fix defined elsewhere in the input
script. The compute or fix must produce either a global vector or
array. If it produces a global vector, then the notation without "[N]"
should be used. If it produces a global array, then the notation with
"[N]" should be used, where N is an integer, to specify which column of
the global array is being referenced. The last form of argument
"v_name" is for a vector-style variable where "name" is replaced by the
name of the variable.
These functions operate on a global vector of inputs and reduce it to
a single scalar value. This is analogous to the operation of the
:doc:`compute reduce <compute_reduce>` command, which performs similar
operations on per-atom and local vectors.
The sum(x), min(x), max(x), ave(x), trap(x), and slope(x) functions
operate on a global vector of inputs and reduce it to a single scalar
value. This is analogous to the operation of the :doc:`compute reduce
<compute_reduce>` command, which performs similar operations on per-atom
and local vectors.
The sort(x) and rsort(x) functions operate on a global vector of inputs
and return a global vector of the same length.
The sum() function calculates the sum of all the vector elements. The
min() and max() functions find the minimum and maximum element
@ -953,6 +957,12 @@ of points, equally spaced by 1 in their x coordinate: (1,V1), (2,V2),
length N. The returned value is the slope of the line. If the line
has a single point or is vertical, it returns 1.0e20.
.. versionadded:: TBD
The sort(x) and rsort(x) functions sort the data of the input vector by
their numeric value: sort(x) sorts in ascending order, rsort(x) sorts
in descending order.
The gmask(x) function takes 1 argument which is a group ID. It
can only be used in atom-style variables. It returns a 1 for
atoms that are in the group, and a 0 for atoms that are not.

6
doc/src/write_data.rst
View File

@ -12,14 +12,14 @@ Syntax
* file = name of data file to write out
* zero or more keyword/value pairs may be appended
* keyword = *pair* or *nocoeff* or *nofix* or *nolabelmap*
* keyword = *nocoeff* or *nofix* or *nolabelmap* or *triclinic/general* or *types* or *pair*
.. parsed-literal::
*nocoeff* = do not write out force field info
*nofix* = do not write out extra sections read by fixes
*nolabelmap* = do not write out type labels
*triclinic/general = write data file in general triclinic format
*triclinic/general* = write data file in general triclinic format
*types* value = *numeric* or *labels*
*pair* value = *ii* or *ij*
*ii* = write one line of pair coefficient info per atom type
@ -189,4 +189,4 @@ Related commands
Default
"""""""
The option defaults are pair = ii and types_style = numeric.
The option defaults are pair = ii and types = numeric.