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

finalized dump command support for general triclinic

Browse Source
This commit is contained in:
Steve Plimpton
2023-11-20 12:06:58 -07:00
parent 92b02041cb
commit dfafdff209
11 changed files with 319 additions and 153 deletions
Download Patch File Download Diff File Expand all files Collapse all files

141
doc/src/create_atoms.rst
View File

@ -112,6 +112,21 @@ added to the specified atom *type* (e.g., if *type* = 2 and the file
specifies atom types 1, 2, and 3, then each created molecule will have
atom types 3, 4, and 5).
.. note::
You cannot use this command to create atoms that are outside the
simulation box; they will just be ignored by LAMMPS. This is true
even if you are using shrink-wrapped box boundaries, as specified
by the :doc:`boundary <boundary>` command. However, you can first
use the :doc:`change_box <change_box>` command to temporarily
expand the box, then add atoms via create_atoms, then finally use
change_box command again if needed to re-shrink-wrap the new atoms.
See the :doc:`change_box <change_box>` doc page for an example of
how to do this, using the create_atoms *single* style to insert a
new atom outside the current simulation box.
----------
For the *box* style, the create_atoms command fills the entire
simulation box with particles on the lattice. If your simulation box
is periodic, you should ensure its size is a multiple of the lattice
@ -182,7 +197,64 @@ styles should be made in that context.
For the *single* style, a single particle is added to the system at
the specified coordinates. This can be useful for debugging purposes
or to create a tiny system with a handful of particles at specified
positions.
positions. For a 2d simulation the specified z coordinate must be
0.0.
.. versionchanged:: 2Jun2022
The *porosity* style has been renamed to *random* with added functionality.
For the *random* style, *N* particles are added to the system at
randomly generated coordinates, which can be useful for generating an
amorphous system. For 2d simulations, the z coordinates of all added
atoms will be 0.0.
The particles are created one by one using the specified random number
*seed*, resulting in the same set of particle coordinates, independent
of how many processors are being used in the simulation. Unless the
*overlap* keyword is specified, particles created by the *random*
style will typically be highly overlapped. Various additional
criteria can be used to accept or reject a random particle insertion;
see the keyword discussion below. Multiple attempts per particle are
made (see the *maxtry* keyword) until the insertion is either
successful or fails. If this command fails to add all requested *N*
particles, a warning will be output.
If the *region-ID* argument is specified as NULL, then the randomly
created particles will be anywhere in the simulation box. If a
*region-ID* is specified, a geometric volume is filled that is both
inside the simulation box and is also consistent with the region
volume. See the :doc:`region <region>` command for details. Note
that a region can be specified so that its "volume" is either inside
or outside its geometric boundary.
Note that the create_atoms command adds particles to those that
already exist. This means it can be used to add particles to a system
previously read in from a data or restart file. Or the create_atoms
command can be used multiple times, to add multiple sets of particles
to the simulation. For example, grain boundaries can be created, by
interleaving the create_atoms command with :doc:`lattice <lattice>`
commands specifying different orientations.
When this command is used, care should be taken to ensure the
resulting system does not contain particles that are highly
overlapped. Such overlaps will cause many interatomic potentials to
compute huge energies and forces, leading to bad dynamics. There are
several strategies to avoid this problem:
* Use the :doc:`delete_atoms overlap <delete_atoms>` command after
create_atoms. For example, this strategy can be used to overlay and
surround a large protein molecule with a volume of water molecules,
then delete water molecules that overlap with the protein atoms.
* For the *random* style, use the optional *overlap* keyword to avoid
overlaps when each new particle is created.
* Before running dynamics on an overlapped system, perform an
:doc:`energy minimization <minimize>`. Or run initial dynamics with
:doc:`pair_style soft <pair_soft>` or with :doc:`fix nve/limit
<fix_nve_limit>` to un-overlap the particles, before running normal
dynamics.
.. figure:: img/marble_race.jpg
:figwidth: 33%
@ -242,73 +314,6 @@ to the area of that triangle.
beneficial to exclude computing interactions between the created
particles using :doc:`neigh_modify exclude <neigh_modify>`.
.. versionchanged:: 2Jun2022
The *porosity* style has been renamed to *random* with added functionality.
For the *random* style, *N* particles are added to the system at
randomly generated coordinates, which can be useful for generating an
amorphous system. The particles are created one by one using the
specified random number *seed*, resulting in the same set of particle
coordinates, independent of how many processors are being used in the
simulation. Unless the *overlap* keyword is specified, particles
created by the *random* style will typically be highly overlapped.
Various additional criteria can be used to accept or reject a random
particle insertion; see the keyword discussion below. Multiple
attempts per particle are made (see the *maxtry* keyword) until the
insertion is either successful or fails. If this command fails to add
all requested *N* particles, a warning will be output.
If the *region-ID* argument is specified as NULL, then the randomly
created particles will be anywhere in the simulation box. If a
*region-ID* is specified, a geometric volume is filled that is both
inside the simulation box and is also consistent with the region
volume. See the :doc:`region <region>` command for details. Note
that a region can be specified so that its "volume" is either inside
or outside its geometric boundary.
Note that the create_atoms command adds particles to those that
already exist. This means it can be used to add particles to a system
previously read in from a data or restart file. Or the create_atoms
command can be used multiple times, to add multiple sets of particles
to the simulation. For example, grain boundaries can be created, by
interleaving the create_atoms command with :doc:`lattice <lattice>`
commands specifying different orientations.
When this command is used, care should be taken to ensure the
resulting system does not contain particles that are highly
overlapped. Such overlaps will cause many interatomic potentials to
compute huge energies and forces, leading to bad dynamics. There are
several strategies to avoid this problem:
* Use the :doc:`delete_atoms overlap <delete_atoms>` command after
create_atoms. For example, this strategy can be used to overlay and
surround a large protein molecule with a volume of water molecules,
then delete water molecules that overlap with the protein atoms.
* For the *random* style, use the optional *overlap* keyword to avoid
overlaps when each new particle is created.
* Before running dynamics on an overlapped system, perform an
:doc:`energy minimization <minimize>`. Or run initial dynamics with
:doc:`pair_style soft <pair_soft>` or with :doc:`fix nve/limit
<fix_nve_limit>` to un-overlap the particles, before running normal
dynamics.
.. note::
You cannot use any of the styles explained above to create atoms
that are outside the simulation box; they will just be ignored by
LAMMPS. This is true even if you are using shrink-wrapped box
boundaries, as specified by the :doc:`boundary <boundary>` command.
However, you can first use the :doc:`change_box <change_box>`
command to temporarily expand the box, then add atoms via
create_atoms, then finally use change_box command again if needed
to re-shrink-wrap the new atoms. See the :doc:`change_box
<change_box>` doc page for an example of how to do this, using the
create_atoms *single* style to insert a new atom outside the
current simulation box.
----------
Individual atoms are inserted by this command, unless the *mol*

108
doc/src/dump.rst
View File

@ -278,16 +278,20 @@ format <dump_modify>` command and its options.
Format of native LAMMPS format dump files:
The *atom*, *custom*, *grid*, and *local* styles create files in a
simple LAMMPS-specific text format that is self-explanatory when
viewing a dump file. Many post-processing tools either included with
LAMMPS or third-party tools can read this format, as does the
simple LAMMPS-specific text format that is mostly self-explanatory
when viewing a dump file. Many post-processing tools either included
with LAMMPS or third-party tools can read this format, as does the
:doc:`rerun <rerun>` command. See tools described on the :doc:`Tools
<Tools>` doc page for examples, including `Pizza.py
<https://lammps.github.io/pizza>`_.
For all these styles, the dimensions of the simulation box are
included in each snapshot. For an orthogonal simulation box this
information is formatted as:
included in each snapshot. The simulation box in LAMMPS can be
defined in one of 3 ways: orthogonal, restricted triclinic, and
general triclinic. See the :doc:`Howto triclinic <Howto_triclininc>`
doc page for a detailed description of all 3 options.
For an orthogonal simulation box the box information is formatted as:
.. parsed-literal::
@ -304,10 +308,10 @@ the six characters is one of *p* (periodic), *f* (fixed), *s* (shrink wrap),
or *m* (shrink wrapped with a minimum value). See the
:doc:`boundary <boundary>` command for details.
For triclinic simulation boxes (non-orthogonal), an orthogonal
bounding box which encloses the triclinic simulation box is output,
along with the three tilt factors (*xy*, *xz*, *yz*) of the triclinic box,
formatted as follows:
For a restricted triclinic simulation box, an orthogonal bounding box
which encloses the restricted triclinic simulation box is output,
along with the three tilt factors (*xy*, *xz*, *yz*) of the triclinic
box, formatted as follows:
.. parsed-literal::
@ -329,6 +333,10 @@ bounding box extents (xlo_bound, xhi_bound, etc.) are calculated from the
triclinic parameters, and how to transform those parameters to and
from other commonly used triclinic representations.
For a general triclinic simulation box, see the "General triclinic"
section below for a description of the ITEM: BOX BOUNDS format as well
as how per-atom coordinates and per-atom vector quantities are output.
The *atom* and *custom* styles output a "ITEM: NUMBER OF ATOMS" line
with the count of atoms in the snapshot. Likewise they output an
"ITEM: ATOMS" line which includes column descriptors for the per-atom
@ -400,7 +408,6 @@ command.
Dump files in other popular formats:
.. note::
This section only discusses file formats relevant to this doc page.
@ -656,6 +663,87 @@ how to control the compression level in both variants.
----------
General triclinic simulation box output for the *atom* and *custom* styles:
As mentioned above, the simulation box can be defined as a general
triclinic box, which means that 3 arbitrary box edge vectors **A**,
**B**, **C** can be specified. See the :doc:`Howto triclinic
<Howto_triclininc>` doc page for a detailed description of general
triclinic boxes.
This option is provided as a convenience for users who may be
converting data from solid-state crystallograhic representations or
from DFT codes for input to LAMMPS. However, as explained on the
:doc:`Howto_triclinic <Howto_triclinic>` doc page, internally, LAMMPS
only uses restricted triclinic simulation boxes. This means the box
and per-atom information (e.g. coordinates, velocities) LAMMPS stores
are converted (rotated) from general to restricted triclinic form when
the system is created.
For dump output, if the :doc:`dump_modify triclinic/general
<dump_modify>` command is used, the box description and per-atom
coordinates and other per-atom vectors will be converted (rotated)
from restricted to general form when each dump file snapshots is
output. This option can only be used if the simulation box was
initially created as general triclinic. If the option is not used,
and the simulation box is general triclinic, then the dump file
snapshots will reflect the internal restricted triclinic geometry.
The dump_modify triclinic/general option affects 3 aspects of the dump
file output.
First, the format for the BOX BOUNDS is as follows
.. parsed-literal::
ITEM: BOX BOUNDS abc origin
ax ay az originx
bx by bz originy
cx cy cz originz
where the **A** edge vector of the box is (ax,ay,az) and similarly
for **B** and **C**. The origin of all 3 edge vectors is (originx,
originy, originz).
Second, the coordinates of each atom are converted (rotated) so that
the atom is inside (or near) the general triclinic box defined by the
**A**, **B**, **C** edge vectors. For style *atom*, this only alters
output for unscaled atom coords, via the :doc:`dump_modify scaled no
<dump_modify>` setting. For style *custom*, this alters output for
either unscaled or unwrapped output of atom coords, via the *x,y,z* or
*xu,yu,zu* attributes. For output of scaled atom coords by both
styles, there is no difference bewteen restricted and general
triclinic values.
Third, the output for any attribute of the *custom* style which
represents a per-atom vector quantity will be converted (rotated) to
be oriented consistent with the general tricinic box and its
orientation relative to the standard xyz coordinate axes.
This applies to the following *custom* style attributes:
* vx,vy,vz = atom velocities
* fx,fy,fz = forces on atoms
* mux,muy,muz = orientation of dipole moment of atom
* omegax,omegay,omegaz = angular velocity of spherical particle
* angmomx,angmomy,angmomz = angular momentum of aspherical particle
* tqx,tqy,tqz = torque on finite-size particles
For example, if the velocity of an atom in a restricted triclinic box
is along the x-axis, then it will be output for a general triclinic
box as a vector along the **A** edge vector of the box.
.. note::
For style *custom*, the :doc:`dump_modify thresh <dump_modify>`
command may access per-atom attributes either directly or
indirectly through a compute or variable. If the attribute is an
atom coordinate or one of the vectors mentioned above, its value
will *NOT* be a general triclinic (rotated) value. Rather it will
be a restricted triclinic value.
----------
Arguments for different styles:
The sections below describe per-atom, local, and per grid cell

45
doc/src/dump_modify.rst
View File

@ -17,7 +17,7 @@ Syntax
* one or more keyword/value pairs may be appended
* these keywords apply to various dump styles
* keyword = *append* or *at* or *balance* or *buffer* or *colname* or *delay* or *element* or *every* or *every/time* or *fileper* or *first* or *flush* or *format* or *header* or *image* or *label* or *maxfiles* or *nfile* or *pad* or *pbc* or *precision* or *region* or *refresh* or *scale* or *sfactor* or *skip* or *sort* or *tfactor* or *thermo* or *thresh* or *time* or *units* or *unwrap*
* keyword = *append* or *at* or *balance* or *buffer* or *colname* or *delay* or *element* or *every* or *every/time* or *fileper* or *first* or *flush* or *format* or *header* or *image* or *label* or *maxfiles* or *nfile* or *pad* or *pbc* or *precision* or *region* or *refresh* or *scale* or *sfactor* or *skip* or *sort* or *tfactor* or *thermo* or *thresh* or *time* or *triclinic/general* or *units* or *unwrap*
.. parsed-literal::
@ -74,12 +74,13 @@ Syntax
-N = sort per-atom lines in descending order by the Nth column
*tfactor* arg = time scaling factor (> 0.0)
*thermo* arg = *yes* or *no*
*time* arg = *yes* or *no*
*thresh* args = attribute operator value
attribute = same attributes (x,fy,etotal,sxx,etc) used by dump custom style
operator = "<" or "<=" or ">" or ">=" or "==" or "!=" or "\|\^"
value = numeric value to compare to, or LAST
these 3 args can be replaced by the word "none" to turn off thresholding
*time* arg = *yes* or *no*
*triclinic/general* arg = none
*units* arg = *yes* or *no*
*unwrap* arg = *yes* or *no*
@ -802,8 +803,9 @@ region since the last dump.
dump_modify ... thresh v_charge |^ LAST
This will dump atoms whose charge has changed from an absolute value
less than :math:`\frac12` to greater than :math:`\frac12` (or vice versa) since the last dump (e.g., due to reactions and subsequent charge equilibration in a
reactive force field).
less than :math:`\frac12` to greater than :math:`\frac12` (or vice
versa) since the last dump (e.g., due to reactions and subsequent
charge equilibration in a reactive force field).
The choice of operators listed above are the usual comparison
operators. The XOR operation (exclusive or) is also included as "\|\^".
@ -811,6 +813,18 @@ In this context, XOR means that if either the attribute or value is
0.0 and the other is non-zero, then the result is "true" and the
threshold criterion is met. Otherwise it is not met.
.. note::
For style *custom*, the *triclinic/general* keyword alters dump
output for general triclinic simulation boxes and their atoms. See
the :doc:`dump <dump>` command for details of how this changes the
format of dump file snapstots. The thresh keyword may access
per-atom attributes either directly or indirectly through a compute
or variable. If the attribute is an atom coordinate or a per-atom
vector (such as velocity, force, or dipole moment), its value will
*NOT* be a general triclinic (rotated) value. Rather it will be a
restricted triclinic value.
----------
The *time* keyword only applies to the dump *atom*, *custom*, *local*,
@ -835,6 +849,27 @@ The default setting is *no*\ .
----------
The *triclinic/general* keyword only applies to the dump *atom* and
*custom* styles. It can only be used if the simulation box was
created as a general triclinic box. See the :doc:`Howto_triclinic
<Howto_triclinic>` doc page for a detailed explanation of orthogonal,
restricted triclinic, and general triclinic simulation boxes.
If this keyword is used, the box information at the beginning of each
snapshot will include information about the 3 arbitrary edge vectors
**A**, **B**, **C** that define the general triclinic box as well as
their origin. The format is described on the :doc:`dump <dump>` doc
page.
The coordinates of each atom will be output as values in (or near) the
general triclinic box. Likewise, per-atom vector quantities such as
velocity, omega, dipole moment, etc will have orientations consistent
with the general triclinic box, meaning they will be rotated relative
to the standard xyz coordinate axes. See the :doc:`dump <dump>` doc
page for a full list of which dump attributes this affects.
----------
The *units* keyword only applies to the dump *atom*, *custom*, and
*local* styles (and their COMPRESS package versions *atom/gz*,
*custom/gz* and *local/gz*\ ). If set to *yes*, each individual dump
@ -922,6 +957,8 @@ The option defaults are
* sort = off for dump styles *atom*, *custom*, *cfg*, and *local*
* sort = id for dump styles *dcd*, *xtc*, and *xyz*
* thresh = none
* time = no
* triclinic/general not specified
* units = no
* unwrap = no