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

Merge branch 'develop' into doc-write-data

Browse Source
This commit is contained in:
Axel Kohlmeyer
2024-05-13 13:38:21 -04:00
parent 33525de598 f747bb975f
commit 84f06aa7a8
58 changed files with 2748 additions and 695 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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).

13
doc/src/create_atoms.rst
View File

@ -468,12 +468,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::

19
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*,

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

12
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.
@ -233,5 +233,5 @@ 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.

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 sytems 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 infomation) 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.