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

Merge branch 'develop' into document-style-flags

Browse Source
This commit is contained in:
Axel Kohlmeyer
2022-11-30 13:57:45 -05:00
parent a3e7106f31 e76e864152
commit 479e5ca862
171 changed files with 3528 additions and 1885 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
doc/src/Commands_all.rst
View File

@ -31,7 +31,6 @@ table above.
* :doc:`bond_style <bond_style>`
* :doc:`bond_write <bond_write>`
* :doc:`boundary <boundary>`
* :doc:`box <box>`
* :doc:`change_box <change_box>`
* :doc:`clear <clear>`
* :doc:`comm_modify <comm_modify>`
@ -90,8 +89,7 @@ table above.
* :doc:`region <region>`
* :doc:`replicate <replicate>`
* :doc:`rerun <rerun>`
* :doc:`reset_atom_ids <reset_atom_ids>`
* :doc:`reset_mol_ids <reset_mol_ids>`
* :doc:`reset_atoms <reset_atoms>`
* :doc:`reset_timestep <reset_timestep>`
* :doc:`restart <restart>`
* :doc:`run <run>`

1
doc/src/Commands_category.rst
View File

@ -25,7 +25,6 @@ Setup simulation box:
:columns: 4
* :doc:`boundary <boundary>`
* :doc:`box <box>`
* :doc:`change_box <change_box>`
* :doc:`create_box <create_box>`
* :doc:`dimension <dimension>`

50
doc/src/Commands_removed.rst
View File

@ -2,10 +2,11 @@ Removed commands and packages
=============================
This page lists LAMMPS commands and packages that have been removed from
the distribution and provides suggestions for alternatives or replacements.
LAMMPS has special dummy styles implemented, that will stop LAMMPS and
print a suitable error message in most cases, when a style/command is used
that has been removed.
the distribution and provides suggestions for alternatives or
replacements. LAMMPS has special dummy styles implemented, that will
stop LAMMPS and print a suitable error message in most cases, when a
style/command is used that has been removed or will replace the command
with the direct alternative (if available) and print a warning.
Fix ave/spatial and fix ave/spatial/sphere
------------------------------------------
@ -17,10 +18,23 @@ ways through the :doc:`compute chunk/atom <compute_chunk_atom>` command
and then averaging is done using :doc:`fix ave/chunk <fix_ave_chunk>`.
Please refer to the :doc:`chunk HOWTO <Howto_chunk>` section for an overview.
Reset_ids command
-----------------
Box command
-----------
The reset_ids command has been renamed to :doc:`reset_atom_ids <reset_atom_ids>`.
.. deprecated:: TBD
The *box* command has been removed and the LAMMPS code changed so it won't
be needed. If present, LAMMPS will ignore the command and print a warning.
Reset_ids, reset_atom_ids, reset_mol_ids commands
-------------------------------------------------
.. deprecated:: TBD
The *reset_ids*, *reset_atom_ids*, and *reset_mol_ids* commands have
been folded into the :doc:`reset_atoms <reset_atoms>` command. If
present, LAMMPS will replace the commands accordingly and print a
warning.
MEAM package
------------
@ -30,18 +44,21 @@ The code in the :ref:`MEAM package <PKG-MEAM>` is a translation of the
Fortran code of MEAM into C++, which removes several restrictions
(e.g. there can be multiple instances in hybrid pair styles) and allows
for some optimizations leading to better performance. The pair style
:doc:`meam <pair_meam>` has the exact same syntax.
:doc:`meam <pair_meam>` has the exact same syntax. For a transition
period the C++ version of MEAM was called USER-MEAMC so it could
coexist with the Fortran version.
REAX package
------------
The REAX package has been removed since it was superseded by the
:ref:`REAXFF package <PKG-REAXFF>`. The REAXFF
package has been tested to yield equivalent results to the REAX package,
offers better performance, supports OpenMP multi-threading via OPENMP,
and GPU and threading parallelization through KOKKOS. The new pair styles
are not syntax compatible with the removed reax pair style, so input
files will have to be adapted.
:ref:`REAXFF package <PKG-REAXFF>`. The REAXFF package has been tested
to yield equivalent results to the REAX package, offers better
performance, supports OpenMP multi-threading via OPENMP, and GPU and
threading parallelization through KOKKOS. The new pair styles are not
syntax compatible with the removed reax pair style, so input files will
have to be adapted. The REAXFF package was originally called
USER-REAXC.
USER-CUDA package
-----------------
@ -60,5 +77,6 @@ restart2data tool
The functionality of the restart2data tool has been folded into the
LAMMPS executable directly instead of having a separate tool. A
combination of the commands :doc:`read_restart <read_restart>` and
:doc:`write_data <write_data>` can be used to the same effect. For added
convenience this conversion can also be triggered by :doc:`command line flags <Run_options>`
:doc:`write_data <write_data>` can be used to the same effect. For
added convenience this conversion can also be triggered by
:doc:`command line flags <Run_options>`

8
doc/src/Developer_code_design.rst
View File

@ -78,7 +78,7 @@ LAMMPS makes extensive use of the object oriented programming (OOP)
principles of *compositing* and *inheritance*. Classes like the
``LAMMPS`` class are a **composite** containing pointers to instances
of other classes like ``Atom``, ``Comm``, ``Force``, ``Neighbor``,
``Modify``, and so on. Each of these classes implement certain
``Modify``, and so on. Each of these classes implements certain
functionality by storing and manipulating data related to the
simulation and providing member functions that trigger certain
actions. Some of those classes like ``Force`` are themselves
@ -87,9 +87,9 @@ interactions. Similarly the ``Modify`` class contains a list of
``Fix`` and ``Compute`` classes. If the input commands that
correspond to these classes include the word *style*, then LAMMPS
stores only a single instance of that class. E.g. *atom_style*,
*comm_style*, *pair_style*, *bond_style*. It the input command does
not include the word *style*, there can be many instances of that
class defined. E.g. *region*, *fix*, *compute*, *dump*.
*comm_style*, *pair_style*, *bond_style*. If the input command does
**not** include the word *style*, then there may be many instances of
that class defined, for example *region*, *fix*, *compute*, *dump*.
**Inheritance** enables creation of *derived* classes that can share
common functionality in their base class while providing a consistent

6
doc/src/Developer_unittest.rst
View File

@ -226,9 +226,9 @@ The following test programs are currently available:
* - ``test_kim_commands.cpp``
- KimCommands
- Tests for several commands from the :ref:`KIM package <PKG-KIM>`
* - ``test_reset_ids.cpp``
- ResetIDs
- Tests to validate the :doc:`reset_atom_ids <reset_atom_ids>` and :doc:`reset_mol_ids <reset_mol_ids>` commands
* - ``test_reset_atoms.cpp``
- ResetAtoms
- Tests to validate the :doc:`reset_atoms <reset_atoms>` sub-commands
Tests for the C-style library interface

5
doc/src/Howto_triclinic.rst
View File

@ -144,11 +144,6 @@ does not change the atom positions due to non-periodicity. In this
mode, if you tilt the system to extreme angles, the simulation will
simply become inefficient, due to the highly skewed simulation box.
The limitation on not creating a simulation box with a tilt factor
skewing the box more than half the distance of the parallel box length
can be overridden via the :doc:`box <box>` command. Setting the *tilt*
keyword to *large* allows any tilt factors to be specified.
Box flips that may occur using the :doc:`fix deform <fix_deform>` or
:doc:`fix npt <fix_nh>` commands can be turned off using the *flip no*
option with either of the commands.

2
doc/src/Run_options.rst
View File

@ -262,6 +262,8 @@ Disable generating a citation reminder (see above) at all.
**-nonbuf**
.. versionadded:: 15Sep2022
Turn off buffering for screen and logfile output. For performance
reasons, output to the screen and logfile is usually buffered, i.e.
output is only written to a file if its buffer - typically 4096 bytes -

18
doc/src/angle_gaussian.rst
View File

@ -25,23 +25,25 @@ The *gaussian* angle style uses the potential:
.. math::
E = -k_B T ln\left(\sum_{i=1}^{n} \frac{A_i}{w_i \sqrt{\pi/2}} exp\left( \frac{-(\theta-\theta_{i})^2}{w_i^2})\right) \right)
E = -k_B T ln\left(\sum_{i=1}^{n} \frac{A_i}{w_i \sqrt{\pi/2}} exp\left( \frac{-2(\theta-\theta_{i})^2}{w_i^2}\right) \right)
This analytical form is a suitable potential for obtaining mesoscale
effective force fields which can reproduce target atomistic
distributions :ref:`(Milano) <Milano1>`.
This analytical form is a suitable potential for obtaining
mesoscale effective force fields which can reproduce target atomistic distributions :ref:`(Milano) <Milano1>`
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* T temperature at which the potential was derived
* :math:`T` temperature at which the potential was derived
* :math:`n` (integer >=1)
* :math:`A_1` (-)
* :math:`w_1` (-)
* :math:`A_1` (> 0, radians)
* :math:`w_1` (> 0, radians)
* :math:`\theta_1` (degrees)
* ...
* :math:`A_n` (-)
* :math:`w_n` (-)
* :math:`A_n` (> 0, radians)
* :math:`w_n` (> 0, radians)
* :math:`\theta_n` (degrees)

8
doc/src/bond_bpm_rotational.rst
View File

@ -45,6 +45,8 @@ Examples
Description
"""""""""""
.. versionadded:: 4May2022
The *bpm/rotational* bond style computes forces and torques 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
@ -211,9 +213,9 @@ command, as *b1*, *b2*, ..., *b7*\ .
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the BPM
package. See the :doc:`Build package <Build_package>` doc page for
more info.
This bond style is part of the BPM package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
By default if pair interactions are to be disabled, this bond style
requires setting

8
doc/src/bond_bpm_spring.rst
View File

@ -45,6 +45,8 @@ Examples
Description
"""""""""""
.. versionadded:: 4May2022
The *bpm/spring* bond style computes forces and torques 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
@ -167,9 +169,9 @@ extra quantity can be accessed by the
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the BPM
package. See the :doc:`Build package <Build_package>` doc page for
more info.
This bond style is part of the BPM package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
By default if pair interactions are to be disabled, this bond style
requires setting

25
doc/src/bond_gaussian.rst
View File

@ -25,33 +25,34 @@ The *gaussian* bond style uses the potential:
.. math::
E = -k_B T ln\left(\sum_{i=1}^{n} \frac{A_i}{w_i \sqrt{\pi/2}} exp\left( \frac{-(r-r_{i})^2}{w_i^2})\right) \right)
E = -k_B T ln\left(\sum_{i=1}^{n} \frac{A_i}{w_i \sqrt{\pi/2}} exp\left( \frac{-2(r-r_{i})^2}{w_i^2}\right)\right)
This analytical form is a suitable potential for obtaining
mesoscale effective force fields which can reproduce target atomistic distributions :ref:`(Milano) <Milano0>`
This analytical form is a suitable potential for obtaining mesoscale
effective force fields which can reproduce target atomistic
distributions :ref:`(Milano) <Milano0>`
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* T temperature at which the potential was derived
* :math:`T` temperature at which the potential was derived
* :math:`n` (integer >=1)
* :math:`A_1` (-)
* :math:`w_1` (-)
* :math:`r_1` (length)
* :math:`A_1` (> 0, distance)
* :math:`w_1` (> 0, distance)
* :math:`r_1` (>= 0, distance)
* ...
* :math:`A_n` (-)
* :math:`w_n` (-)
* :math:`r_n` (length)
* :math:`A_n` (> 0, distance)
* :math:`w_n` (> 0, distance)
* :math:`r_n` (>= 0, distance)
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the
EXTRA-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
""""""""""""""""

70
doc/src/box.rst
View File

@ -1,70 +0,0 @@
.. index:: box
box command
===========
Syntax
""""""
.. code-block:: LAMMPS
box keyword value ...
* one or more keyword/value pairs may be appended
* keyword = *tilt*
.. parsed-literal::
*tilt* value = *small* or *large*
Examples
""""""""
.. code-block:: LAMMPS
box tilt large
box tilt small
Description
"""""""""""
Set attributes of the simulation box.
For triclinic (non-orthogonal) simulation boxes, the *tilt* keyword
allows simulation domains to be created with arbitrary tilt factors,
e.g. via the :doc:`create_box <create_box>` or
:doc:`read_data <read_data>` commands. Tilt factors determine how
skewed the triclinic box is; see the :doc:`Howto triclinic <Howto_triclinic>` page for a discussion of triclinic
boxes in LAMMPS.
LAMMPS normally requires that no tilt factor can skew the box more
than half the distance of the parallel box length, which is the first
dimension in the tilt factor (x for xz). If *tilt* is set to
*small*, which is the default, then an error will be
generated if a box is created which exceeds this limit. If *tilt*
is set to *large*, then no limit is enforced. You can create
a box with any tilt factors you wish.
Note that if a simulation box has a large tilt factor, LAMMPS will run
less efficiently, due to the large volume of communication needed to
acquire ghost atoms around a processor's irregular-shaped sub-domain.
For extreme values of tilt, LAMMPS may also lose atoms and generate an
error.
Restrictions
""""""""""""
This command cannot be used after the simulation box is defined by a
:doc:`read_data <read_data>` or :doc:`create_box <create_box>` command or
:doc:`read_restart <read_restart>` command.
Related commands
""""""""""""""""
none
Default
"""""""
The default value is tilt = small.

4
doc/src/commands_list.rst
View File

@ -13,7 +13,6 @@ Commands
bond_style
bond_write
boundary
box
change_box
clear
comm_modify
@ -90,8 +89,7 @@ Commands
region
replicate
rerun
reset_atom_ids
reset_mol_ids
reset_atoms
reset_timestep
restart
run

7
doc/src/compute_nbond_atom.rst
View File

@ -23,6 +23,8 @@ Examples
Description
"""""""""""
.. versionadded:: 4May2022
Define a computation that computes the number of bonds each atom is
part of. Bonds which are broken are not counted in the tally. See
the :doc:`Howto broken bonds <Howto_bpm>` page for more information.
@ -40,8 +42,9 @@ LAMMPS output options.
Restrictions
""""""""""""
This fix can only be used if LAMMPS was built with the BPM package.
See the :doc:`Build package <Build_package>` doc page for more info.
This compute is part of the BPM package. It is only enabled if LAMMPS was
built with that package. See the :doc:`Build package <Build_package>`
page for more info.
Related commands
""""""""""""""""

2
doc/src/compute_pair_local.rst
View File

@ -59,7 +59,7 @@ commands.
The value *dist* is the distance between the pair of atoms.
The values *dx*, *dy*, and *dz* are the :math:`(x,y,z)` components of the
*distance* between the pair of atoms. This value is always the
distance from the atom of lower to the one with the higher id.
distance from the atom of higher to the one with the lower atom ID.
The value *eng* is the interaction energy for the pair of atoms.

25
doc/src/create_box.rst
View File

@ -66,20 +66,21 @@ positive or negative values and are called "tilt factors" because they
are the amount of displacement applied to faces of an originally
orthogonal box to transform it into the parallelepiped.
By default, a *prism* region used with the create_box command must
have tilt factors :math:`(xy,xz,yz)` that do not skew the box more than half
By default, a *prism* region used with the create_box command must have
tilt factors :math:`(xy,xz,yz)` that do not skew the box more than half
the distance of the parallel box length. For example, if
:math:`x_\text{lo} = 2` and :math:`x_\text{hi} = 12`, then the :math:`x`
box length is 10 and the :math:`xy` tilt factor must be between :math:`-5` and
:math:`5`. Similarly, both :math:`xz` and :math:`yz` must be between
:math:`-(x_\text{hi}-x_\text{lo})/2` and :math:`+(y_\text{hi}-y_\text{lo})/2`.
Note that this is not a limitation, since if the maximum tilt factor is 5 (as
in this example), then configurations with tilt :math:`= \dots, -15`,
:math:`-5`, :math:`5`, :math:`15`, :math:`25, \dots`
are all geometrically equivalent. If you wish to define a box with tilt
factors that exceed these limits, you can use the :doc:`box tilt <box>`
command, with a setting of *large*\ ; a setting of *small* is the
default.
box length is 10 and the :math:`xy` tilt factor must be between
:math:`-5` and :math:`5`. Similarly, both :math:`xz` and :math:`yz`
must be between :math:`-(x_\text{hi}-x_\text{lo})/2` and
:math:`+(y_\text{hi}-y_\text{lo})/2`. Note that this is not a
limitation, since if the maximum tilt factor is 5 (as in this example),
then configurations with tilt :math:`= \dots, -15`, :math:`-5`,
:math:`5`, :math:`15`, :math:`25, \dots` are all geometrically
equivalent. Simulations with large tilt factors will run inefficiently,
since they require more ghost atoms and thus more communication. With
very large tilt factors, LAMMPS will eventually produce incorrect
trajectories and stop with errors due to lost atoms or similar.
See the :doc:`Howto triclinic <Howto_triclinic>` page for a
geometric description of triclinic boxes, as defined by LAMMPS, and

4
doc/src/delete_atoms.rst
View File

@ -135,7 +135,7 @@ number of atoms in the system. Note that this is not done for
molecular systems (see the :doc:`atom_style <atom_style>` command),
regardless of the *compress* setting, since it would foul up the bond
connectivity that has already been assigned. However, the
:doc:`reset_atom_ids <reset_atom_ids>` command can be used after this
:doc:`reset_atoms id <reset_atoms>` command can be used after this
command to accomplish the same thing.
Note that the re-assignment of IDs is not really a compression, where
@ -203,7 +203,7 @@ using molecule template files via the :doc:`molecule <molecule>` and
Related commands
""""""""""""""""
:doc:`create_atoms <create_atoms>`, :doc:`reset_atom_ids <reset_atom_ids>`
:doc:`create_atoms <create_atoms>`, :doc:`reset_atoms id <reset_atoms>`
Default
"""""""

2
doc/src/dump_image.rst
View File

@ -69,7 +69,7 @@ Syntax
yes/no = do or do not draw simulation box lines
diam = diameter of box lines as fraction of shortest box length
*axes* values = axes length diam = draw xyz axes
axes = *yes* or *no = do or do not draw xyz axes lines next to simulation box
axes = *yes* or *no* = do or do not draw xyz axes lines next to simulation box
length = length of axes lines as fraction of respective box lengths
diam = diameter of axes lines as fraction of shortest box length
*subbox* values = lines diam = draw outline of processor sub-domains

113
doc/src/fix_bond_react.rst
View File

@ -42,13 +42,16 @@ Syntax
* template-ID(post-reacted) = ID of a molecule template containing post-reaction topology
* map_file = name of file specifying corresponding atom-IDs in the pre- and post-reacted templates
* zero or more individual keyword/value pairs may be appended to each react argument
* individual_keyword = *prob* or *max_rxn* or *stabilize_steps* or *custom_charges* or *molecule* or *modify_create*
* individual_keyword = *prob* or *rate_limit* or *max_rxn* or *stabilize_steps* or *custom_charges* or *rescale_charges* or *molecule* or *modify_create*
.. parsed-literal::
*prob* values = fraction seed
fraction = initiate reaction with this probability if otherwise eligible
seed = random number seed (positive integer)
*rate_limit* = Nlimit Nsteps
Nlimit = maximum number of reactions allowed to occur within interval
Nsteps = the interval (number of timesteps) over which to count reactions
*max_rxn* value = N
N = maximum number of reactions allowed to occur
*stabilize_steps* value = timesteps
@ -56,6 +59,9 @@ Syntax
*custom_charges* value = *no* or fragment-ID
*no* = update all atomic charges (default)
fragment-ID = ID of molecule fragment whose charges are updated
*rescale_charges* value = *no* or *yes*
*no* = do not rescale atomic charges (default)
*yes* = rescale charges such that total charge does not change during reaction
*molecule* value = *off* or *inter* or *intra*
*off* = allow both inter- and intramolecular reactions (default)
*inter* = search for reactions between molecules with different IDs
@ -171,12 +177,12 @@ due to the internal dynamic grouping performed by fix bond/react.
If the group-ID is an existing static group, react-group-IDs
should also be specified as this static group or a subset.
The *reset_mol_ids* keyword invokes the :doc:`reset_mol_ids <reset_mol_ids>`
command after a reaction occurs, to ensure that molecule IDs are
consistent with the new bond topology. The group-ID used for
:doc:`reset_mol_ids <reset_mol_ids>` is the group-ID for this fix.
Resetting molecule IDs is necessarily a global operation, so it can
be slow for very large systems.
The *reset_mol_ids* keyword invokes the :doc:`reset_atoms mol
<reset_atoms>` command after a reaction occurs, to ensure that
molecule IDs are consistent with the new bond topology. The group-ID
used for :doc:`reset_atoms mol <reset_atoms>` is the group-ID for this
fix. Resetting molecule IDs is necessarily a global operation, so it
can be slow for very large systems.
The following comments pertain to each *react* argument (in other
words, they can be customized for each reaction, or reaction step):
@ -514,28 +520,40 @@ example, the molecule fragment could consist of only the backbone
atoms of a polymer chain. This constraint can be used to enforce a
specific relative position and orientation between reacting molecules.
.. versionchanged:: TBD
The constraint of type "custom" has the following syntax:
.. parsed-literal::
custom *varstring*
where "custom" is the required keyword, and *varstring* is a
variable expression. The expression must be a valid equal-style
variable formula that can be read by the :doc:`variable <variable>` command,
where 'custom' is the required keyword, and *varstring* is a variable
expression. The expression must be a valid equal-style variable
formula that can be read by the :doc:`variable <variable>` command,
after any special reaction functions are evaluated. If the resulting
expression is zero, the reaction is prevented from occurring;
otherwise, it is permitted to occur. There are two special reaction
functions available, "rxnsum" and "rxnave". These functions operate
over the atoms in a given reaction site, and have one mandatory
argument and one optional argument. The mandatory argument is the
identifier for an atom-style variable. The second, optional argument
is the name of a molecule fragment in the pre-reaction template, and
can be used to operate over a subset of atoms in the reaction site.
The "rxnsum" function sums the atom-style variable over the reaction
site, while the "rxnave" returns the average value. For example, a
constraint on the total potential energy of atoms involved in the
reaction can be imposed as follows:
otherwise, it is permitted to occur. There are three special reaction
functions available, 'rxnbond', 'rxnsum', and 'rxnave'. The 'rxnbond'
function allows per-bond values to be included in the variable strings
of the custom constraint. The 'rxnbond' function has two mandatory
arguments. The first argument is the ID of a previously defined
'compute bond/local' command. This 'compute bond/local' must compute
only one value, e.g. bond force. This value is returned by the
'rxnbond' function. The second argument is the name of a molecule
fragment in the pre-reaction template. The fragment must contain
exactly two atoms, corresponding to the atoms involved in the bond
whose value should be calculated. An example of a constraint that uses
the force experienced by a bond is provided below. The 'rxnsum' and
'rxnave' functions operate over the atoms in a given reaction site,
and have one mandatory argument and one optional argument. The
mandatory argument is the identifier for an atom-style variable. The
second, optional argument is the name of a molecule fragment in the
pre-reaction template, and can be used to operate over a subset of
atoms in the reaction site. The 'rxnsum' function sums the atom-style
variable over the reaction site, while the 'rxnave' returns the
average value. For example, a constraint on the total potential energy
of atoms involved in the reaction can be imposed as follows:
.. code-block:: LAMMPS
@ -547,11 +565,32 @@ reaction can be imposed as follows:
custom "rxnsum(v_my_pe) > 100" # in Constraints section of map file
The above example prevents the reaction from occurring unless the
total potential energy of the reaction site is above 100. The variable
expression can be interpreted as the probability of the reaction
occurring by using an inequality and the :doc:`random(x,y,z) <variable>`
function available for equal-style variables, similar to the 'arrhenius'
constraint above.
total potential energy of the reaction site is above 100. As a second
example, this time using the 'rxnbond' function, consider a modified
Arrhenius constraint that depends on the bond force of a specific bond:
.. code-block:: LAMMPS
# in LAMMPS input script
compute bondforce all bond/local force
compute ke_atom all ke/atom
variable ke atom c_ke_atom
variable E_a equal 100.0 # activation energy
variable l0 equal 1.0 # characteristic length
.. code-block:: LAMMPS
# in Constraints section of map file
custom "exp(-(v_E_a-rxnbond(c_bondforce,bond1frag)*v_l0)/(2/3*rxnave(v_ke))) < random(0,1,12345)"
By using an inequality and the 'random(x,y,z)' function, the left-hand
side can be interpreted as the probability of the reaction occurring,
similar to the 'arrhenius' constraint above.
By default, all constraints must be satisfied for the reaction to
occur. In other words, constraints are evaluated as a series of
@ -598,6 +637,15 @@ eligible reaction only occurs if the random number is less than the
fraction. Up to :math:`N` reactions are permitted to occur, as optionally
specified by the *max_rxn* keyword.
.. versionadded:: TBD
The *rate_limit* keyword can enforce an upper limit on the overall
rate of the reaction. The number of reaction occurrences is limited to
Nlimit within an interval of Nsteps timesteps. No reactions are
permitted to occur within the first Nsteps timesteps of the first run
after reading a data file. Nlimit can be specified with an equal-style
:doc:`variable <variable>`.
The *stabilize_steps* keyword allows for the specification of how many
time steps a reaction site is stabilized before being returned to the
overall system thermostat. In order to produce the most physical
@ -616,6 +664,19 @@ charges are updated to those specified by the post-reaction template
fragment defined in the pre-reaction molecule template. In this case,
only the atomic charges of atoms in the molecule fragment are updated.
.. versionadded:: TBD
The *rescale_charges* keyword can be used to ensure the total charge
of the system does not change as reactions occur. When the argument is
set to *yes*\ , a fixed value is added to the charges of post-reaction
atoms such that their total charge equals that of the pre-reaction
site. If only a subset of atomic charges are updated via the
*custom_charges* keyword, this rescaling is applied to the subset.
This keyword could be useful for systems that contain different
molecules with the same reactive site, if the partial charges on the
reaction site vary from molecule to molecule, or when removing
reaction by-products.
The *molecule* keyword can be used to force the reaction to be
intermolecular, intramolecular or either. When the value is set to
*off*\ , molecule IDs are not considered when searching for reactions

6
doc/src/fix_ipi.rst
View File

@ -90,6 +90,12 @@ coordinates are transferred. However, one could use this strategy to
define an external potential acting on the atoms that are moved by
i-PI.
Since the i-PI code uses atomic units internally, this fix needs to
convert LAMMPS data to and from its :doc:`specified units <units>`
accordingly when communicating with i-PI. This is not possible for
reduced units ("units lj") and thus *fix ipi* will stop with an error in
this case.
This fix is part of the MISC package. It is only enabled if
LAMMPS was built with that package. See the
:doc:`Build package <Build_package>` page for more info.

97
doc/src/fix_nh_uef.rst
View File

@ -44,19 +44,23 @@ Examples
Description
"""""""""""
This fix can be used to simulate non-equilibrium molecular dynamics
(NEMD) under diagonal flow fields, including uniaxial and bi-axial
flow. Simulations under continuous extensional flow may be carried
out for an indefinite amount of time. It is an implementation of the
boundary conditions from :ref:`(Dobson) <Dobson>`, and also uses numerical
These fixes can be used to simulate non-equilibrium molecular dynamics
(NEMD) under diagonal flow fields, including uniaxial and bi-axial flow.
Simulations under continuous extensional flow may be carried out for an
indefinite amount of time. It is an implementation of the boundary
conditions from :ref:`(Dobson) <Dobson>`, and also uses numerical
lattice reduction as was proposed by :ref:`(Hunt) <Hunt>`. The lattice
reduction algorithm is from :ref:`(Semaev) <Semaev>`. The fix is intended for
simulations of homogeneous flows, and integrates the SLLOD equations
of motion, originally proposed by Hoover and Ladd (see :ref:`(Evans and Morriss) <Sllod>`). Additional detail about this implementation can be
found in :ref:`(Nicholson and Rutledge) <Nicholson>`.
reduction algorithm is from :ref:`(Semaev) <Semaev>`. The fix is
intended for simulations of homogeneous flows, and integrates the SLLOD
equations of motion, originally proposed by Hoover and Ladd (see
:ref:`(Evans and Morriss) <Sllod>`). Additional detail about this
implementation can be found in :ref:`(Nicholson and Rutledge)
<Nicholson>`.
Note that NEMD simulations of a continuously strained system can be
performed using the :doc:`fix deform <fix_deform>`, :doc:`fix nvt/sllod <fix_nvt_sllod>`, and :doc:`compute temp/deform <compute_temp_deform>` commands.
performed using the :doc:`fix deform <fix_deform>`, :doc:`fix nvt/sllod
<fix_nvt_sllod>`, and :doc:`compute temp/deform <compute_temp_deform>`
commands.
The applied flow field is set by the *eps* keyword. The values
*edot_x* and *edot_y* correspond to the strain rates in the xx and yy
@ -73,11 +77,11 @@ to -(*edot_x* + *edot_y*).
The boundary conditions require a simulation box that does not have a
consistent alignment relative to the applied flow field. Since LAMMPS
utilizes an upper-triangular simulation box, it is not possible to
express the evolving simulation box in the same coordinate system as
the flow field. This fix keeps track of two coordinate systems: the
flow frame, and the upper triangular LAMMPS frame. The coordinate
systems are related to each other through the QR decomposition, as is
illustrated in the image below.
express the evolving simulation box in the same coordinate system as the
flow field. These fixes keep track of two coordinate systems: the flow
frame, and the upper triangular LAMMPS frame. The coordinate systems are
related to each other through the QR decomposition, as is illustrated in
the image below.
.. image:: JPG/uef_frames.jpg
:align: center
@ -99,12 +103,12 @@ using the dump command will be in the LAMMPS frame unless the
----------
Temperature control is achieved with the default Nose-Hoover style
thermostat documented in :doc:`fix npt <fix_nh>`. When this fix is
thermostat documented in :doc:`fix nvt <fix_nh>`. When this fix is
active, only the peculiar velocity of each atom is stored, defined as
the velocity relative to the streaming velocity. This is in contrast
to :doc:`fix nvt/sllod <fix_nvt_sllod>`, which uses a lab-frame
velocity, and removes the contribution from the streaming velocity in
order to compute the temperature.
the velocity relative to the streaming velocity. This is in contrast to
:doc:`fix nvt/sllod <fix_nvt_sllod>`, which uses a lab-frame velocity,
and removes the contribution from the streaming velocity in order to
compute the temperature.
Pressure control is achieved using the default Nose-Hoover barostat
documented in :doc:`fix npt <fix_nh>`. There are two ways to control the
@ -156,8 +160,8 @@ The following commands will not work:
----------
These fix computes a temperature and pressure each timestep. To do
this, it creates its own computes of style "temp/uef" and
These fixes compute a temperature and pressure each timestep. To do
this, they create their own computes of style "temp/uef" and
"pressure/uef", as if one of these two sets of commands had been
issued:
@ -169,18 +173,19 @@ issued:
compute fix-ID_temp all temp/uef
compute fix-ID_press all pressure/uef fix-ID_temp
See the :doc:`compute temp/uef <compute_temp_uef>` and :doc:`compute pressure/uef <compute_pressure_uef>` commands for details. Note
that the IDs of the new computes are the fix-ID + underscore + "temp"
or fix_ID + underscore + "press".
See the :doc:`compute temp/uef <compute_temp_uef>` and :doc:`compute
pressure/uef <compute_pressure_uef>` commands for details. Note that
the IDs of the new computes are the fix-ID + underscore + "temp" or
fix_ID + underscore + "press".
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
The fix writes the state of all the thermostat and barostat variables,
as well as the cumulative strain applied, to :doc:`binary restart files <restart>`. See the :doc:`read_restart <read_restart>` command
for info on how to re-specify a fix in an input script that reads a
restart file, so that the operation of the fix continues in an
uninterrupted fashion.
as well as the cumulative strain applied, to :doc:`binary restart files
<restart>`. See the :doc:`read_restart <read_restart>` command for info
on how to re-specify a fix in an input script that reads a restart file,
so that the operation of the fix continues in an uninterrupted fashion.
.. note::
@ -189,43 +194,41 @@ uninterrupted fashion.
not contain the cumulative applied strain, will this keyword be
necessary.
This fix can be used with the :doc:`fix_modify <fix_modify>` *temp* and
*press* options. The temperature and pressure computes used must be of
type *temp/uef* and *pressure/uef*\ .
These fixes can be used with the :doc:`fix_modify <fix_modify>` *temp*
and *press* options. The temperature and pressure computes used must be
of type *temp/uef* and *pressure/uef*\ .
This fix computes the same global scalar and vector quantities as :doc:`fix npt <fix_nh>`.
These fixes compute the same global scalar and vector quantities as
:doc:`fix nvt andnpt <fix_nh>`.
The fix is not invoked during :doc:`energy minimization <minimize>`.
These fixes are not invoked during :doc:`energy minimization <minimize>`.
Restrictions
""""""""""""
This fix is part of the UEF 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 UEF package. They are only enabled if LAMMPS
was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
Due to requirements of the boundary conditions, when the *strain*
keyword is set to zero (or unset), the initial simulation box must be
cubic and have style triclinic. If the box is initially of type ortho,
use :doc:`change_box <change_box>` before invoking the fix.
.. note::
When resuming from restart files, you may need to use :doc:`box tilt
large <box>` since LAMMPS has internal criteria from lattice
reduction that are not the same as the criteria in the numerical
lattice reduction algorithm.
Related commands
""""""""""""""""
:doc:`fix nvt <fix_nh>`, :doc:`fix nvt/sllod <fix_nvt_sllod>`, :doc:`compute temp/uef <compute_temp_uef>`, :doc:`compute pressure/uef <compute_pressure_uef>`, :doc:`dump cfg/uef <dump_cfg_uef>`
:doc:`fix nvt <fix_nh>`, :doc:`fix npt <fix_nh>`, `fix nvt/sllod
:doc:<fix_nvt_sllod>`, `compute temp/uef <compute_temp_uef>`,
:doc::doc:`compute pressure/uef <compute_pressure_uef>`, `dump cfg/uef
:doc:<dump_cfg_uef>`
Default
"""""""
The default keyword values specific to this fix are exy = xyz, strain
= 0 0. The remaining defaults are the same as for :doc:`fix npt <fix_nh>`
except tchain = 1. The reason for this change is given in
The default keyword values specific to these fixes are exy = xyz, strain
= 0 0. The remaining defaults are the same as for :doc:`fix nvt or npt
<fix_nh>` except tchain = 1. The reason for this change is given in
:doc:`fix nvt/sllod <fix_nvt_sllod>`.
----------

6
doc/src/fix_nve_bpm_sphere.rst
View File

@ -30,6 +30,8 @@ Examples
Description
"""""""""""
.. versionadded:: 4May2022
Perform constant NVE integration to update position, velocity, angular
velocity, and quaternion orientation for finite-size spherical
particles in the group each timestep. V is volume; E is energy. This
@ -65,6 +67,10 @@ the :doc:`run <run>` command. This fix is not invoked during
Restrictions
""""""""""""
This fix is part of the BPM package. It is only enabled if LAMMPS was
built with that package. See the :doc:`Build package <Build_package>`
page for more info.
This fix requires that atoms store torque, angular velocity (omega), a
radius, and a quaternion as defined by the :doc:`atom_style bpm/sphere
<atom_style>` command.

2
doc/src/fix_pimd.rst
View File

@ -156,6 +156,8 @@ This fix is part of the REPLICA package. It is only enabled if
LAMMPS was built with that package. See the
:doc:`Build package <Build_package>` page for more info.
Fix pid cannot be used with :doc:`lj units <units>`.
A PIMD simulation can be initialized with a single data file read via
the :doc:`read_data <read_data>` command. However, this means all
quasi-beads in a ring polymer will have identical positions and

8
doc/src/pair_bpm_spring.rst
View File

@ -22,6 +22,8 @@ Examples
Description
"""""""""""
.. versionadded:: 4May2022
Style *bpm/spring* computes pairwise forces with the formula
.. math::
@ -101,7 +103,11 @@ This pair style can only be used via the *pair* keyword of the
Restrictions
""""""""""""
none
This pair style is part of the BPM package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
Related commands
""""""""""""""""

10
doc/src/pair_sw.rst
View File

@ -176,9 +176,13 @@ are placeholders for atom types that will be used with other potentials.
.. note::
When the *threebody off* keyword is used, multiple pair_coeff commands may
be used to specific the pairs of atoms which don't require three-body term.
In these cases, the first 2 arguments are not required to be \* \*.
When the *threebody off* keyword is used, multiple pair_coeff
commands may be used to specific the pairs of atoms which don't
require three-body term. In these cases, the first 2 arguments are
not required to be \* \*, the potential parameter file is only read
by the first :doc:`pair_coeff command <pair_coeff>` and the element
to atom type mappings must be consistent across all *pair_coeff*
statements. If not LAMMPS will abort with an error.
Stillinger-Weber files in the *potentials* directory of the LAMMPS
distribution have a ".sw" suffix. Lines that are not blank or

2
doc/src/pair_ylz.rst
View File

@ -82,7 +82,7 @@ mixing as described below:
* :math:`\epsilon` = well depth (energy units)
* :math:`\sigma` = minimum effective particle radii (distance units)
* :math:`\zeta` = tune parameter for the slope of the attractive branch
* :math:`\zeta` = tuning parameter for the slope of the attractive branch
* :math:`\mu` = parameter related to bending rigidity
* :math:`\beta` = parameter related to the spontaneous curvature
* cutoff (distance units)

347
doc/src/python.rst
View File

@ -8,14 +8,25 @@ Syntax
.. parsed-literal::
python func keyword args ...
python mode keyword args ...
* func = name of Python function
* one or more keyword/args pairs must be appended
* mode = *source* or name of Python function
if mode is *source*:
.. parsed-literal::
keyword = *invoke* or *input* or *return* or *format* or *length* or *file* or *here* or *exists* or *source*
keyword = *here* or name of a *Python file*
*here* arg = inline
inline = one or more lines of Python code which defines func
must be a single argument, typically enclosed between triple quotes
*Python file* = name of a file with Python code which will be executed immediately
* if *mode* is the name of a Python function, one or more keywords with/without arguments must be appended
.. parsed-literal::
keyword = *invoke* or *input* or *return* or *format* or *length* or *file* or *here* or *exists*
*invoke* arg = none = invoke the previously defined Python function
*input* args = N i1 i2 ... iN
N = # of inputs to function
@ -24,7 +35,7 @@ Syntax
SELF = reference to LAMMPS itself which can be accessed by Python function
variable = v_name, where name = name of LAMMPS variable, e.g. v_abc
*return* arg = varReturn
varReturn = v_name = LAMMPS variable name which return value of function will be assigned to
varReturn = v_name = LAMMPS variable name which the return value of the Python function will be assigned to
*format* arg = fstring with M characters
M = N if no return value, where N = # of inputs
M = N+1 if there is a return value
@ -38,10 +49,6 @@ Syntax
inline = one or more lines of Python code which defines func
must be a single argument, typically enclosed between triple quotes
*exists* arg = none = Python code has been loaded by previous python command
*source* arg = *filename* or *inline*
filename = file of Python code which will be executed immediately
inline = one or more lines of Python code which will be executed immediately
must be a single argument, typically enclosed between triple quotes
Examples
""""""""
@ -70,80 +77,105 @@ Examples
lmp.command("pair_style lj/cut ${cut}") # LAMMPS commands
lmp.command("pair_coeff * * 1.0 1.0")
lmp.command("run 100")
"""
"""
python source funcdef.py
python source here "from lammps import lammps"
Description
"""""""""""
Define a Python function or execute a previously defined function or
execute some arbitrary python code.
The *python* command allows interfacing LAMMPS with an embedded Python
interpreter and enables either executing arbitrary python code in that
interpreter, registering a Python function for future execution (as a
python style variable, from a fix interfaced with python, or for direct
invocation), or invoking such a previously registered function.
Arguments, including LAMMPS variables, can be passed to the function
from the LAMMPS input script and a value returned by the Python
function to a LAMMPS variable. The Python code for the function can
be included directly in the input script or in a separate Python file.
The function can be standard Python code or it can make "callbacks" to
LAMMPS through its library interface to query or set internal values
within LAMMPS. This is a powerful mechanism for performing complex
operations in a LAMMPS input script that are not possible with the
simple input script and variable syntax which LAMMPS defines. Thus
your input script can operate more like a true programming language.
from the LAMMPS input script and a value returned by the Python function
assigned to a LAMMPS variable. The Python code for the function can be included
directly in the input script or in a separate Python file. The function
can be standard Python code or it can make "callbacks" to LAMMPS through
its library interface to query or set internal values within LAMMPS.
This is a powerful mechanism for performing complex operations in a
LAMMPS input script that are not possible with the simple input script
and variable syntax which LAMMPS defines. Thus your input script can
operate more like a true programming language.
Use of this command requires building LAMMPS with the PYTHON package
which links to the Python library so that the Python interpreter is
embedded in LAMMPS. More details about this process are given below.
There are two ways to invoke a Python function once it has been
defined. One is using the *invoke* keyword. The other is to assign
registered. One is using the *invoke* keyword. The other is to assign
the function to a :doc:`python-style variable <variable>` defined in
your input script. Whenever the variable is evaluated, it will
execute the Python function to assign a value to the variable. Note
that variables can be evaluated in many different ways within LAMMPS.
They can be substituted for directly in an input script. Or they can
be passed to various commands as arguments, so that the variable is
evaluated during a simulation run.
your input script. Whenever the variable is evaluated, it will execute
the Python function to assign a value to the variable. Note that
variables can be evaluated in many different ways within LAMMPS. They
can be substituted with their result directly in an input script, or
they can be passed to various commands as arguments, so that the
variable is evaluated during a simulation run.
A broader overview of how Python can be used with LAMMPS is given on
the :doc:`Python <Python_head>` doc page. There is an examples/python
directory which illustrates use of the python command.
A broader overview of how Python can be used with LAMMPS is given in the
:doc:`Use Python with LAMMPS <Python_head>` section of the
documentation. There also is an ``examples/python`` directory which
illustrates use of the python command.
----------
The *func* setting specifies the name of the Python function. The
code for the function is defined using the *file* or *here* keywords
as explained below. In case of the *source* keyword, the name of
the function is ignored.
The first argument of the *python* command is either the *source*
keyword or the name of a Python function. This defines the mode
of the python command.
.. versionchanged:: TBD
If the *source* keyword is used, it is followed by either a file name or
the *here* keyword. No other keywords can be used. The *here* keyword
is followed by a string with python commands, either on a single line
enclosed in quotes, or as multiple lines enclosed in triple quotes.
These Python commands will be passed to the python interpreter and
executed immediately without registering a Python function for future
execution. The code will be loaded into and run in the "main" module of
the Python interpreter. This allows running arbitrary Python code at
any time while processing the LAMMPS input file. This can be used to
pre-load Python modules, initialize global variables, define functions
or classes, or perform operations using the python programming language.
The Python code will be executed in parallel on all MPI processes. No
arguments can be passed.
In all other cases, the first argument is the name of a Python function
that will be registered with LAMMPS for future execution. The function
may already be defined (see *exists* keyword) or must be defined using
the *file* or *here* keywords as explained below.
If the *invoke* keyword is used, no other keywords can be used, and a
previous python command must have defined the Python function
previous *python* command must have registered the Python function
referenced by this command. This invokes the Python function with the
previously defined arguments and return value processed as explained
below. You can invoke the function as many times as you wish in your
input script.
If the *source* keyword is used, no other keywords can be used.
The argument can be a filename or a string with python commands,
either on a single line enclosed in quotes, or as multiple lines
enclosed in triple quotes. These python commands will be passed
to the python interpreter and executed immediately without registering
a python function for future execution.
previously defined arguments and the return value is processed as
explained below. You can invoke the function as many times as you wish
in your input script.
The *input* keyword defines how many arguments *N* the Python function
expects. If it takes no arguments, then the *input* keyword should
not be used. Each argument can be specified directly as a value,
e.g. 6 or 3.14159 or abc (a string of characters). The type of each
expects. If it takes no arguments, then the *input* keyword should not
be used. Each argument can be specified directly as a value, e.g. '6'
or '3.14159' or 'abc' (a string of characters). The type of each
argument is specified by the *format* keyword as explained below, so
that Python will know how to interpret the value. If the word SELF is
used for an argument it has a special meaning. A pointer is passed to
the Python function which it converts into a reference to LAMMPS
itself. This enables the function to call back to LAMMPS through its
library interface as explained below. This allows the Python function
to query or set values internal to LAMMPS which can affect the
subsequent execution of the input script. A LAMMPS variable can also
be used as an argument, specified as v_name, where "name" is the name
of the variable. Any style of LAMMPS variable can be used, as defined
by the :doc:`variable <variable>` command. Each time the Python
function is invoked, the LAMMPS variable is evaluated and its value is
passed to the Python function.
the Python function which it can convert into a reference to LAMMPS
itself using the :doc:`LAMMPS Python module <Python_module>`. This
enables the function to call back to LAMMPS through its library
interface as explained below. This allows the Python function to query
or set values internal to LAMMPS which can affect the subsequent
execution of the input script. A LAMMPS variable can also be used as an
argument, specified as v_name, where "name" is the name of the variable.
Any style of LAMMPS variable returning a scalar or a string can be used,
as defined by the :doc:`variable <variable>` command. The *format*
keyword must be used to set the type of data that is passed to Python.
Each time the Python function is invoked, the LAMMPS variable is
evaluated and its value is passed to the Python function.
The *return* keyword is only needed if the Python function returns a
value. The specified *varReturn* must be of the form v_name, where
@ -153,8 +185,9 @@ numeric or string value, as specified by the *format* keyword.
As explained on the :doc:`variable <variable>` doc page, the definition
of a python-style variable associates a Python function name with the
variable. This must match the *func* setting for this command. For
example these two commands would be self-consistent:
variable. This must match the *Python function name* first argument of
the *python* command. For example these two commands would be
consistent:
.. code-block:: LAMMPS
@ -163,21 +196,22 @@ example these two commands would be self-consistent:
The two commands can appear in either order in the input script so
long as both are specified before the Python function is invoked for
the first time.
the first time. Afterwards, the variable 'foo' is associated with
the Python function 'myMultiply'.
The *format* keyword must be used if the *input* or *return* keyword
is used. It defines an *fstring* with M characters, where M = sum of
The *format* keyword must be used if the *input* or *return* keywords
are used. It defines an *fstring* with M characters, where M = sum of
number of inputs and outputs. The order of characters corresponds to
the N inputs, followed by the return value (if it exists). Each
character must be one of the following: "i" for integer, "f" for
floating point, "s" for string, or "p" for SELF. Each character
defines the type of the corresponding input or output value of the
Python function and affects the type conversion that is performed
internally as data is passed back and forth between LAMMPS and Python.
Note that it is permissible to use a :doc:`python-style variable <variable>` in a LAMMPS command that allows for an
equal-style variable as an argument, but only if the output of the
Python function is flagged as a numeric value ("i" or "f") via the
*format* keyword.
floating point, "s" for string, or "p" for SELF. Each character defines
the type of the corresponding input or output value of the Python
function and affects the type conversion that is performed internally as
data is passed back and forth between LAMMPS and Python. Note that it
is permissible to use a :doc:`python-style variable <variable>` in a
LAMMPS command that allows for an equal-style variable as an argument,
but only if the output of the Python function is flagged as a numeric
value ("i" or "f") via the *format* keyword.
If the *return* keyword is used and the *format* keyword specifies the
output as a string, then the default maximum length of that string is
@ -192,12 +226,13 @@ truncated.
Either the *file*, *here*, or *exists* keyword must be used, but only
one of them. These keywords specify what Python code to load into the
Python interpreter. The *file* keyword gives the name of a file,
which should end with a ".py" suffix, which contains Python code. The
code will be immediately loaded into and run in the "main" module of
the Python interpreter. Note that Python code which contains a
function definition does not "execute" the function when it is run; it
simply defines the function so that it can be invoked later.
Python interpreter. The *file* keyword gives the name of a file
containing Python code, which should end with a ".py" suffix. The code
will be immediately loaded into and run in the "main" module of the
Python interpreter. The Python code will be executed in parallel on all
MPI processes. Note that Python code which contains a function
definition does not "execute" the function when it is run; it simply
defines the function so that it can be invoked later.
The *here* keyword does the same thing, except that the Python code
follows as a single argument to the *here* keyword. This can be done
@ -208,14 +243,15 @@ proper indentation, blank lines, and comments, as desired. See the
how triple quotes can be used as part of input script syntax.
The *exists* keyword takes no argument. It means that Python code
containing the required Python function defined by the *func* setting,
is assumed to have been previously loaded by another python command.
containing the required Python function with the given name has already
been executed, for example by a *python source* command or in the same
file that was used previously with the *file* keyword.
Note that the Python code that is loaded and run must contain a
function with the specified *func* name. To operate properly when
later invoked, the function code must match the *input* and
*return* and *format* keywords specified by the python command.
Otherwise Python will generate an error.
Note that the Python code that is loaded and run must contain a function
with the specified function name. To operate properly when later
invoked, the function code must match the *input* and *return* and
*format* keywords specified by the python command. Otherwise Python
will generate an error.
----------
@ -225,19 +261,19 @@ LAMMPS.
Whether you load Python code from a file or directly from your input
script, via the *file* and *here* keywords, the code can be identical.
It must be indented properly as Python requires. It can contain
comments or blank lines. If the code is in your input script, it
cannot however contain triple-quoted Python strings, since that will
conflict with the triple-quote parsing that the LAMMPS input script
performs.
comments or blank lines. If the code is in your input script, it cannot
however contain triple-quoted Python strings, since that will conflict
with the triple-quote parsing that the LAMMPS input script performs.
All the Python code you specify via one or more python commands is
loaded into the Python "main" module, i.e. __main__. The code can
define global variables or statements that are outside of function
definitions. It can contain multiple functions, only one of which
matches the *func* setting in the python command. This means you can
use the *file* keyword once to load several functions, and the
*exists* keyword thereafter in subsequent python commands to access
the other functions previously loaded.
loaded into the Python "main" module, i.e. ``__name__ == '__main__'``.
The code can define global variables, define global functions, define
classes or execute statements that are outside of function definitions.
It can contain multiple functions, only one of which matches the *func*
setting in the python command. This means you can use the *file*
keyword once to load several functions, and the *exists* keyword
thereafter in subsequent python commands to register the other functions
that were previously loaded with LAMMPS.
A Python function you define (or more generally, the code you load)
can import other Python modules or classes, it can make calls to other
@ -264,12 +300,13 @@ outside the function:
nvaluelast = nvalue
return nvalue
Nsteplast stores the previous timestep the function was invoked
(passed as an argument to the function). Nvaluelast stores the return
value computed on the last function invocation. If the function is
invoked again on the same timestep, the previous value is simply
returned, without re-computing it. The "global" statement inside the
Python function allows it to overwrite the global variables.
The variable 'nsteplast' stores the previous timestep the function was
invoked (passed as an argument to the function). The variable
'nvaluelast' stores the return value computed on the last function
invocation. If the function is invoked again on the same timestep, the
previous value is simply returned, without re-computing it. The
"global" statement inside the Python function allows it to overwrite the
global variables from within the local context of the function.
Note that if you load Python code multiple times (via multiple python
commands), you can overwrite previously loaded variables and functions
@ -285,19 +322,39 @@ copy of the Python function(s) you define. There is no connection
between the Python interpreters running on different processors.
This implies three important things.
First, if you put a print statement in your Python function, you will
see P copies of the output, when running on P processors. If the
prints occur at (nearly) the same time, the P copies of the output may
be mixed together. Welcome to the world of parallel programming and
debugging.
First, if you put a print or other statement creating output to the
screen in your Python function, you will see P copies of the output,
when running on P processors. If the prints occur at (nearly) the same
time, the P copies of the output may be mixed together. When loading
the LAMMPS Python module into the embedded Python interpreter, it is
possible to pass the pointer to the current LAMMPS class instance and
via the Python interface to the LAMMPS library interface, it is possible
to determine the MPI rank of the current process and thus adapt the
Python code so that output will only appear on MPI rank 0. The
following LAMMPS input demonstrates how this could be done. The text
'Hello, LAMMPS!' should be printed only once, even when running LAMMPS
in parallel.
Second, if your Python code loads modules that are not pre-loaded by
the Python library, then it will load the module from disk. This may
be a bottleneck if 1000s of processors try to load a module at the
same time. On some large supercomputers, loading of modules from disk
by Python may be disabled. In this case you would need to pre-build a
Python library that has the required modules pre-loaded and link
LAMMPS with that library.
.. code-block:: LAMMPS
python python_hello input 1 SELF format p here """
def python_hello(handle):
from lammps import lammps
lmp = lammps(ptr=handle)
me = lmp.extract_setting('world_rank')
if me == 0:
print('Hello, LAMMPS!')
"""
python python_hello invoke
If your Python code loads Python modules that are not pre-loaded by the
Python library, then it will load the module from disk. This may be a
bottleneck if 1000s of processors try to load a module at the same time.
On some large supercomputers, loading of modules from disk by Python may
be disabled. In this case you would need to pre-build a Python library
that has the required modules pre-loaded and link LAMMPS with that
library.
Third, if your Python code calls back to LAMMPS (discussed in the
next section) and causes LAMMPS to perform an MPI operation requires
@ -315,22 +372,21 @@ Python function is as follows:
.. code-block:: python
def foo(lmpptr,...):
def foo(handle,...):
from lammps import lammps
lmp = lammps(ptr=lmpptr)
lmp = lammps(ptr=handle)
lmp.command('print "Hello from inside Python"')
...
The function definition must include a variable (lmpptr in this case)
which corresponds to SELF in the python command. The first line of the
function imports the :doc:`"lammps" Python module <Python_module>`.
The second line creates a Python object ``lmp`` which
wraps the instance of LAMMPS that called the function. The "ptr=lmpptr"
argument is what makes that happen. The third line invokes the
command() function in the LAMMPS library interface. It takes a single
string argument which is a LAMMPS input script command for LAMMPS to
execute, the same as if it appeared in your input script. In this case,
LAMMPS should output
The function definition must include a variable ('handle' in this case)
which corresponds to SELF in the *python* command. The first line of
the function imports the :doc:`"lammps" Python module <Python_module>`.
The second line creates a Python object ``lmp`` which wraps the instance
of LAMMPS that called the function. The 'ptr=handle' argument is what
makes that happen. The third line invokes the command() function in the
LAMMPS library interface. It takes a single string argument which is a
LAMMPS input script command for LAMMPS to execute, the same as if it
appeared in your input script. In this case, LAMMPS should output
.. parsed-literal::
@ -344,8 +400,8 @@ The :doc:`Python_head` page describes the syntax
for how Python wraps the various functions included in the LAMMPS
library interface.
A more interesting example is in the examples/python/in.python script
which loads and runs the following function from examples/python/funcs.py:
A more interesting example is in the ``examples/python/in.python`` script
which loads and runs the following function from ``examples/python/funcs.py``:
.. code-block:: python
@ -495,24 +551,35 @@ Restrictions
""""""""""""
This command is part of the PYTHON package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package <Build_package>` page for more info.
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
Building LAMMPS with the PYTHON package will link LAMMPS with the
Python library on your system. Settings to enable this are in the
Building LAMMPS with the PYTHON package will link LAMMPS with the Python
library on your system. Settings to enable this are in the
lib/python/Makefile.lammps file. See the lib/python/README file for
information on those settings.
If you use Python code which calls back to LAMMPS, via the SELF input argument
explained above, there is an extra step required when building LAMMPS. LAMMPS
must also be built as a shared library and your Python function must be able to
load the :doc:`"lammps" Python module <Python_module>` that wraps the LAMMPS
library interface. These are the same steps required to use Python by itself
to wrap LAMMPS. Details on these steps are explained on the :doc:`Python
<Python_head>` doc page. Note that it is important that the stand-alone LAMMPS
executable and the LAMMPS shared library be consistent (built from the same
source code files) in order for this to work. If the two have been built at
If you use Python code which calls back to LAMMPS, via the SELF input
argument explained above, there is an extra step required when building
LAMMPS. LAMMPS must also be built as a shared library and your Python
function must be able to load the :doc:`"lammps" Python module
<Python_module>` that wraps the LAMMPS library interface. These are the
same steps required to use Python by itself to wrap LAMMPS. Details on
these steps are explained on the :doc:`Python <Python_head>` doc page.
Note that it is important that the stand-alone LAMMPS executable and the
LAMMPS shared library be consistent (built from the same source code
files) in order for this to work. If the two have been built at
different times using different source files, problems may occur.
Another limitation of calling back to Python from the LAMMPS module
using the *python* command in a LAMMPS input is that both, the Python
interpreter and LAMMPS, must be linked to the same Python runtime as a
shared library. If the Python interpreter is linked to Python
statically (which seems to happen with Conda) then loading the shared
LAMMPS library will create a second python "main" module that hides the
one from the Python interpreter and all previous defined function and
global variables will become invisible.
Related commands
""""""""""""""""

24
doc/src/read_data.rst
View File

@ -340,16 +340,20 @@ and are called "tilt factors" because they are the amount of
displacement applied to faces of an originally orthogonal box to
transform it into the parallelepiped.
By default, the tilt factors (xy,xz,yz) can not skew the box more than
half the distance of the corresponding parallel box length. For
example, if xlo = 2 and xhi = 12, then the x box length is 10 and the
xy tilt factor must be between -5 and 5. Similarly, both xz and yz
must be between -(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not
a limitation, since if the maximum tilt factor is 5 (as in this
example), then configurations with tilt = ..., -15, -5, 5, 15, 25,
... are all geometrically equivalent. If you wish to define a box
with tilt factors that exceed these limits, you can use the :doc:`box tilt <box>` command, with a setting of *large*\ ; a setting of
*small* is the default.
The tilt factors (xy,xz,yz) should not skew the box more than half the
distance of the corresponding parallel box length. For example, if
:math:`x_\text{lo} = 2` and :math:`x_\text{hi} = 12`, then the :math:`x`
box length is 10 and the :math:`xy` tilt factor must be between
:math:`-5` and :math:`5`. Similarly, both :math:`xz` and :math:`yz`
must be between :math:`-(x_\text{hi}-x_\text{lo})/2` and
:math:`+(y_\text{hi}-y_\text{lo})/2`. Note that this is not a
limitation, since if the maximum tilt factor is 5 (as in this example),
then configurations with tilt :math:`= \dots, -15`, :math:`-5`,
:math:`5`, :math:`15`, :math:`25, \dots` are all geometrically
equivalent. Simulations with large tilt factors will run inefficiently,
since they require more ghost atoms and thus more communication. With
very large tilt factors, LAMMPS will eventually produce incorrect
trajectories and stop with errors due to lost atoms or similar.
See the :doc:`Howto triclinic <Howto_triclinic>` page for a
geometric description of triclinic boxes, as defined by LAMMPS, and

94
doc/src/reset_atom_ids.rst
View File

@ -1,94 +0,0 @@
.. index:: reset_atom_ids
reset_atom_ids command
======================
Syntax
""""""
.. code-block:: LAMMPS
reset_atom_ids keyword values ...
* zero or more keyword/value pairs may be appended
* keyword = *sort*
.. parsed-literal::
*sort* value = *yes* or *no*
Examples
""""""""
.. code-block:: LAMMPS
reset_atom_ids
reset_atom_ids sort yes
Description
"""""""""""
Reset atom IDs for the system, including all the global IDs stored
for bond, angle, dihedral, improper topology data. This will
create a set of IDs that are numbered contiguously from 1 to N
for a N atoms system.
This can be useful to do after performing a "delete_atoms" command for
a molecular system. The delete_atoms compress yes option will not
perform this operation due to the existence of bond topology. It can
also be useful to do after any simulation which has lost atoms,
e.g. due to atoms moving outside a simulation box with fixed
boundaries (see the "boundary command"), or due to evaporation (see
the "fix evaporate" command).
If the *sort* keyword is used with a setting of *yes*, then the
assignment of new atom IDs will be the same no matter how many
processors LAMMPS is running on. This is done by first doing a
spatial sort of all the atoms into bins and sorting them within each
bin. Because the set of bins is independent of the number of
processors, this enables a consistent assignment of new IDs to each
atom.
This can be useful to do after using the "create_atoms" command and/or
"replicate" command. In general those commands do not guarantee
assignment of the same atom ID to the same physical atom when LAMMPS
is run on different numbers of processors. Enforcing consistent IDs
can be useful for debugging or comparing output from two different
runs.
Note that the spatial sort requires communication of atom IDs and
coordinates between processors in an all-to-all manner. This is done
efficiently in LAMMPS, but it is more expensive than how atom IDs are
reset without sorting.
Note that whether sorting or not, the resetting of IDs is not a
compression, where gaps in atom IDs are removed by decrementing atom
IDs that are larger. Instead the IDs for all atoms are erased, and
new IDs are assigned so that the atoms owned by an individual
processor have consecutive IDs, as the :doc:`create_atoms
<create_atoms>` command explains.
.. note::
If this command is used before a :doc:`pair style <pair_style>` is
defined, an error about bond topology atom IDs not being found may
result. This is because the cutoff distance for ghost atom
communication was not sufficient to find atoms in bonds, angles, etc
that are owned by other processors. The :doc:`comm_modify cutoff <comm_modify>` command can be used to correct this issue.
Or you can define a pair style before using this command. If you do
the former, you should unset the comm_modify cutoff after using
reset_atom_ids so that subsequent communication is not inefficient.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`delete_atoms <delete_atoms>`
Default
"""""""
By default, *sort* is no.

283
doc/src/reset_atoms.rst Normal file
View File

@ -0,0 +1,283 @@
.. index:: reset_atoms
reset_atoms command
===================
Syntax
""""""
.. code-block:: LAMMPS
reset_atoms property arguments ...
* property = *id* or *image* or *mol*
* additional arguments depend on the property
.. code-block:: LAMMPS
reset_atoms id keyword value ...
* zero or more keyword/value pairs can be appended
* keyword = *sort*
.. parsed-literal::
*sort* value = *yes* or *no*
.. code-block:: LAMMPS
reset_atoms image group-ID
* group-ID = ID of group of atoms whose image flags will be reset
.. code-block:: LAMMPS
reset atoms mol group-ID keyword value ...
* group-ID = ID of group of atoms whose molecule IDs will be reset
* zero or more keyword/value pairs can be appended
* keyword = *compress* or *offset* or *single*
.. parsed-literal::
*compress* value = *yes* or *no*
*offset* value = *Noffset* >= -1
*single* value = *yes* or *no* to treat single atoms (no bonds) as molecules
Examples
""""""""
.. code-block:: LAMMPS
reset_atoms id
reset_atoms id sort yes
reset_atoms image all
reset_atoms image mobile
reset_atoms mol all
reset_atoms mol all offset 10 single yes
reset_atoms mol solvent compress yes offset 100
reset_atoms mol solvent compress no
Description
"""""""""""
.. versionadded:: TBD
The *reset_atoms* command resets the values of a specified atom
property. In contrast to the set command, it does this in a
collective manner which resets the values for many atoms in a
self-consistent way. This is often useful when the simulated system
has undergone significant modifications like adding or removing atoms
or molecules, joining data files, changing bonds, or large-scale
diffusion.
The new values can be thought of as a *reset*, similar to values atoms
would have if a new data file were being read or a new simulation
performed. Note that the set command also resets atom properties to
new values, but it treats each atom independently.
The *property* setting can be *id* or *image* or *mol*. For *id*, the
IDs of all the atoms are reset to contiguous values. For *image*, the
image flags of atoms in the specified *group-ID* are reset so that at
least one atom in each molecule is in the simulation box (image flag =
0). For *mol*, the molecule IDs of all atoms are reset to contiguous
values.
More details on these operations and their arguments or optional
keyword/value settings are given below.
----------
*Property id*
Reset atom IDs for the entire system, including all the global IDs
stored for bond, angle, dihedral, improper topology data. This will
create a set of IDs that are numbered contiguously from 1 to N for a N
atoms system.
This can be useful to do after performing a "delete_atoms" command for
a molecular system. The delete_atoms compress yes option will not
perform this operation due to the existence of bond topology. It can
also be useful to do after any simulation which has lost atoms,
e.g. due to atoms moving outside a simulation box with fixed
boundaries (see the "boundary command"), or due to evaporation (see
the "fix evaporate" command).
If the *sort* keyword is used with a setting of *yes*, then the
assignment of new atom IDs will be the same no matter how many
processors LAMMPS is running on. This is done by first doing a
spatial sort of all the atoms into bins and sorting them within each
bin. Because the set of bins is independent of the number of
processors, this enables a consistent assignment of new IDs to each
atom.
This can be useful to do after using the "create_atoms" command and/or
"replicate" command. In general those commands do not guarantee
assignment of the same atom ID to the same physical atom when LAMMPS
is run on different numbers of processors. Enforcing consistent IDs
can be useful for debugging or comparing output from two different
runs.
Note that the spatial sort requires communication of atom IDs and
coordinates between processors in an all-to-all manner. This is done
efficiently in LAMMPS, but it is more expensive than how atom IDs are
reset without sorting.
Note that whether sorting or not, the resetting of IDs is not a
compression, where gaps in atom IDs are removed by decrementing atom
IDs that are larger. Instead the IDs for all atoms are erased, and
new IDs are assigned so that the atoms owned by an individual
processor have consecutive IDs, as the :doc:`create_atoms
<create_atoms>` command explains.
.. note::
If this command is used before a :doc:`pair style <pair_style>` is
defined, an error about bond topology atom IDs not being found may
result. This is because the cutoff distance for ghost atom
communication was not sufficient to find atoms in bonds, angles, etc
that are owned by other processors. The :doc:`comm_modify cutoff
<comm_modify>` command can be used to correct this issue. Or you can
define a pair style before using this command. If you do the former,
you should unset the *comm_modify cutoff* after using *reset
atoms id* so that subsequent communication is not inefficient.
----------
*Property image*
Reset the image flags of atoms so that at least one atom in each
molecule has an image flag of 0. Molecular topology is respected so
that if the molecule straddles a periodic simulation box boundary, the
images flags of all atoms in the molecule will be consistent. This
avoids inconsistent image flags that could result from resetting all
image flags to zero with the :doc:`set <set>` command.
.. note::
If the system has no bonds, there is no reason to use this command,
since image flags for different atoms do not need to be
consistent. Use the :doc:`set <set>` command with its *image*
keyword instead.
Only image flags for atoms in the specified *group-ID* are reset; all
others remain unchanged. No check is made for whether the group
covers complete molecule fragments and thus whether the command will
result in inconsistent image flags.
Molecular fragments are identified by the algorithm used by the
:doc:`compute fragment/atom <compute_cluster_atom>` command. For each
fragment the average of the largest and the smallest image flag in
each direction across all atoms in the fragment is computed and
subtracted from the current image flag in the same direction.
This can be a useful operation to perform after running longer
equilibration runs of mobile systems where molecules would pass
through the system multiple times and thus produce non-zero image
flags.
.. note::
Same as explained for the :doc:`compute fragment/atom
<compute_cluster_atom>` command, molecules are identified using the
current bond topology. This will **not** account for bonds broken by
the :doc:`bond_style quartic <bond_quartic>` command, because this
bond style does not perform a full update of the bond topology data
structures within LAMMPS. In that case, using the :doc:`delete_bonds
all bond 0 remove <delete_bonds>` will permanently delete such
broken bonds and should thus be used first.
----------
*Property mol*
Reset molecule IDs for a specified group of atoms based on current
bond connectivity. This will typically create a new set of molecule
IDs for atoms in the group. Only molecule IDs for atoms in the
specified *group-ID* are reset; molecule IDs for atoms not in the
group are not changed.
For purposes of this operation, molecules are identified by the current
bond connectivity in the system, which may or may not be consistent with
the current molecule IDs. A molecule in this context is a set of atoms
connected to each other with explicit bonds. The specific algorithm
used is the one of :doc:`compute fragment/atom <compute_cluster_atom>`
Once the molecules are identified and a new molecule ID computed for
each, this command will update the current molecule ID for all atoms in
the group with the new molecule ID. Note that if the group excludes
atoms within molecules, one (physical) molecule may become two or more
(logical) molecules. For example if the group excludes atoms in the
middle of a linear chain, then each end of the chain is considered an
independent molecule and will be assigned a different molecule ID.
This can be a useful operation to perform after running reactive
molecular dynamics run with :doc:`fix bond/react <fix_bond_react>`,
:doc:`fix bond/create <fix_bond_create>`, or :doc:`fix bond/break
<fix_bond_break>`, all of which can change molecule topologies. It can
also be useful after molecules have been deleted with the
:doc:`delete_atoms <delete_atoms>` command or after a simulation which
has lost molecules, e.g. via the :doc:`fix evaporate <fix_evaporate>`
command.
The *compress* keyword determines how new molecule IDs are computed. If
the setting is *yes* (the default) and there are N molecules in the
group, the new molecule IDs will be a set of N contiguous values. See
the *offset* keyword for details on selecting the range of these values.
If the setting is *no*, the molecule ID of every atom in the molecule
will be set to the smallest atom ID of any atom in the molecule.
The *single* keyword determines whether single atoms (not bonded to
another atom) are treated as one-atom molecules or not, based on the
*yes* or *no* setting. If the setting is *no* (the default), their
molecule IDs are set to 0. This setting can be important if the new
molecule IDs will be used as input to other commands such as
:doc:`compute chunk/atom molecule <compute_chunk_atom>` or :doc:`fix
rigid molecule <fix_rigid>`.
The *offset* keyword is only used if the *compress* setting is *yes*.
Its default value is *Noffset* = -1. In that case, if the specified
group is *all*, then the new compressed molecule IDs will range from 1
to N. If the specified group is not *all* and the largest molecule ID
of atoms outside that group is M, then the new compressed molecule IDs will
range from M+1 to M+N, to avoid collision with existing molecule
IDs. If an *Noffset* >= 0 is specified, then the new compressed
molecule IDs will range from *Noffset*\ +1 to *Noffset*\ +N. If the group
is not *all* there may be collisions with the molecule IDs of other atoms.
.. note::
Same as explained for the :doc:`compute fragment/atom
<compute_cluster_atom>` command, molecules are identified using the
current bond topology. This will **not** account for bonds broken by
the :doc:`bond_style quartic <bond_quartic>` command, because this
bond style does not perform a full update of the bond topology data
structures within LAMMPS. In that case, using the :doc:`delete_bonds
all bond 0 remove <delete_bonds>` will permanently delete such broken
bonds and should thus be used first.
Restrictions
""""""""""""
The *image* property can only be used when the atom style supports bonds.
Related commands
""""""""""""""""
:doc:`compute fragment/atom <compute_cluster_atom>`
:doc:`fix bond/react <fix_bond_react>`,
:doc:`fix bond/create <fix_bond_create>`,
:doc:`fix bond/break <fix_bond_break>`,
:doc:`fix evaporate <fix_evaporate>`,
:doc:`delete_atoms <delete_atoms>`,
:doc:`delete_bonds <delete_bonds>`
Defaults
""""""""
For property *id*, the default keyword setting is sort = no.
For property *mol*, the default keyword settings are compress = yes,
single = no, and offset = -1.

116
doc/src/reset_mol_ids.rst
View File

@ -1,116 +0,0 @@
.. index:: reset_mol_ids
reset_mol_ids command
=====================
Syntax
""""""
.. parsed-literal::
reset_mol_ids group-ID keyword value ...
* group-ID = ID of group of atoms whose molecule IDs will be reset
* zero or more keyword/value pairs may be appended
* keyword = *compress* or *offset* or *single*
.. parsed-literal::
*compress* value = *yes* or *no*
*offset* value = *Noffset* >= -1
*single* value = *yes* or *no* to treat single atoms (no bonds) as molecules
Examples
""""""""
.. code-block:: LAMMPS
reset_mol_ids all
reset_mol_ids all offset 10 single yes
reset_mol_ids solvent compress yes offset 100
reset_mol_ids solvent compress no
Description
"""""""""""
Reset molecule IDs for a group of atoms based on current bond
connectivity. This will typically create a new set of molecule IDs
for atoms in the group. Only molecule IDs for atoms in the specified
group are reset; molecule IDs for atoms not in the group are not
changed.
For purposes of this operation, molecules are identified by the current
bond connectivity in the system, which may or may not be consistent with
the current molecule IDs. A molecule in this context is a set of atoms
connected to each other with explicit bonds. The specific algorithm
used is the one of :doc:`compute fragment/atom <compute_cluster_atom>`
Once the molecules are identified and a new molecule ID computed for
each, this command will update the current molecule ID for all atoms in
the group with the new molecule ID. Note that if the group excludes
atoms within molecules, one (physical) molecule may become two or more
(logical) molecules. For example if the group excludes atoms in the
middle of a linear chain, then each end of the chain is considered an
independent molecule and will be assigned a different molecule ID.
This can be a useful operation to perform after running reactive
molecular dynamics run with :doc:`fix bond/react <fix_bond_react>`,
:doc:`fix bond/create <fix_bond_create>`, or :doc:`fix bond/break
<fix_bond_break>`, all of which can change molecule topologies. It can
also be useful after molecules have been deleted with the
:doc:`delete_atoms <delete_atoms>` command or after a simulation which
has lost molecules, e.g. via the :doc:`fix evaporate <fix_evaporate>`
command.
The *compress* keyword determines how new molecule IDs are computed. If
the setting is *yes* (the default) and there are N molecules in the
group, the new molecule IDs will be a set of N contiguous values. See
the *offset* keyword for details on selecting the range of these values.
If the setting is *no*, the molecule ID of every atom in the molecule
will be set to the smallest atom ID of any atom in the molecule.
The *single* keyword determines whether single atoms (not bonded to
another atom) are treated as one-atom molecules or not, based on the
*yes* or *no* setting. If the setting is *no* (the default), their
molecule IDs are set to 0. This setting can be important if the new
molecule IDs will be used as input to other commands such as
:doc:`compute chunk/atom molecule <compute_chunk_atom>` or :doc:`fix
rigid molecule <fix_rigid>`.
The *offset* keyword is only used if the *compress* setting is *yes*.
Its default value is *Noffset* = -1. In that case, if the specified
group is *all*, then the new compressed molecule IDs will range from 1
to N. If the specified group is not *all* and the largest molecule ID
of atoms outside that group is M, then the new compressed molecule IDs will
range from M+1 to M+N, to avoid collision with existing molecule
IDs. If an *Noffset* >= 0 is specified, then the new compressed
molecule IDs will range from *Noffset*\ +1 to *Noffset*\ +N. If the group
is not *all* there may be collisions with the molecule IDs of other atoms.
.. note::
The same as explained for the :doc:`compute fragment/atom
<compute_cluster_atom>` command, molecules are identified using the
current bond topology. This will not account for bonds broken by
the :doc:`bond_style quartic <bond_quartic>` command because it
does not perform a full update of the bond topology data structures
within LAMMPS.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`reset_atom_ids <reset_atom_ids>`, :doc:`fix bond/react <fix_bond_react>`,
:doc:`fix bond/create <fix_bond_create>`,
:doc:`fix bond/break <fix_bond_break>`,
:doc:`fix evaporate <fix_evaporate>`,
:doc:`delete_atoms <delete_atoms>`,
:doc:`compute fragment/atom <compute_cluster_atom>`
Default
"""""""
The default keyword settings are compress = yes, single = no, and
offset = -1.