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

Edits to documentation files for consistency and math

Browse Source
This commit is contained in:
Karl Hammond
2022-08-19 23:49:44 -05:00
parent de0b7bf737
commit 2259947d52
12 changed files with 416 additions and 405 deletions
Download Patch File Download Diff File Expand all files Collapse all files

91
doc/src/create_atoms.rst
View File

@ -95,16 +95,16 @@ typically created via the :doc:`create_box <create_box>` command.
Before using this command, a lattice must also be defined using the
:doc:`lattice <lattice>` command, unless you specify the *single* style
with units = box or the *random* style. For the remainder of this doc
page, a created atom or molecule is referred to as a "particle".
page, a created atom or molecule is referred to as a "particle."
If created particles are individual atoms, they are assigned the
specified atom *type*, though this can be altered via the *basis*
keyword as discussed below. If molecules are being created, the type
of each atom in the created molecule is specified in the file read by
the :doc:`molecule <molecule>` command, and those values are added to
the specified atom *type*\ . E.g. if *type* = 2, and the file specifies
atom types 1,2,3, then each created molecule will have atom types
3,4,5.
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).
For the *box* style, the create_atoms command fills the entire
simulation box with particles on the lattice. If your simulation box
@ -204,7 +204,7 @@ 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 which is both
*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
@ -219,7 +219,7 @@ interleaving the create_atoms command with :doc:`lattice <lattice>`
commands specifying different orientations.
When this command is used, care should be taken to insure the
resulting system does not contain particles which are highly
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:
@ -291,7 +291,7 @@ and inserts all molecules at a specified orientation.
optional keywords allowed by the :doc:`create_box <create_box>` command
for extra bonds (angles,etc) or extra special neighbors. This is
because by default, the :doc:`create_box <create_box>` command sets up a
non-molecular system which does not allow molecules to be added.
non-molecular system that does not allow molecules to be added.
----------
@ -308,11 +308,11 @@ The *ratio* and *subset* keywords can be used in conjunction with the
*box* or *region* styles to limit the total number of particles
inserted. The lattice defines a set of *Nlatt* eligible sites for
inserting particles, which may be limited by the *region* style or the
*var* and *set* keywords. For the *ratio* keyword only the specified
fraction of them (0 <= *frac* <= 1) will be assigned particles. For
the *subset* keyword only the specified *Nsubset* of them will be
*var* and *set* keywords. For the *ratio* keyword, only the specified
fraction of them (:math:`0 \le f \le 1`) will be assigned particles.
For the *subset* keyword only the specified *Nsubset* of them will be
assigned particles. In both cases the assigned lattice sites are
chosen randomly. An iterative algorithm is used which insures the
chosen randomly. An iterative algorithm is used that insures the
correct number of particles are inserted, in a perfectly random
fashion. Which lattice sites are selected will change with the number
of processors used.
@ -327,23 +327,23 @@ The *var* and *set* keywords can be used together to provide a
criterion for accepting or rejecting the addition of an individual
atom, based on its coordinates. They apply to all styles except
*single*. The *name* specified for the *var* keyword is the name of
an :doc:`equal-style variable <variable>` which should evaluate to a
zero or non-zero value based on one or two or three variables which
will store the x, y, or z coordinates of an atom (one variable per
an :doc:`equal-style variable <variable>` that should evaluate to a
zero or non-zero value based on one or two or three variables that
will store the *x*, *y*, or *z* coordinates of an atom (one variable per
coordinate). If used, these other variables must be
:doc:`internal-style variables <variable>` defined in the input
script; their initial numeric value can be anything. They must be
internal-style variables, because this command resets their values
directly. The *set* keyword is used to identify the names of these
other variables, one variable for the x-coordinate of a created atom,
one for y, and one for z.
other variables, one variable for the *x*-coordinate of a created atom,
one for *y*, and one for *z*.
.. figure:: img/sinusoid.jpg
:figwidth: 50%
:align: right
:target: _images/sinusoid.jpg
When an atom is created, its x,y,z coordinates become the values for
When an atom is created, its :math:`(x,y,z)` coordinates become the values for
any *set* variable that is defined. The *var* variable is then
evaluated. If the returned value is 0.0, the atom is not created. If
it is non-zero, the atom is created.
@ -352,8 +352,8 @@ As an example, these commands can be used in a 2d simulation, to
create a sinusoidal surface. Note that the surface is "rough" due to
individual lattice points being "above" or "below" the mathematical
expression for the sinusoidal curve. If a finer lattice were used,
the sinusoid would appear to be "smoother". Also note the use of the
"xlat" and "ylat" :doc:`thermo_style <thermo_style>` keywords which
the sinusoid would appear to be "smoother." Also note the use of the
"xlat" and "ylat" :doc:`thermo_style <thermo_style>` keywords, which
converts lattice spacings to distance.
.. only:: html
@ -379,7 +379,7 @@ converts lattice spacings to distance.
The *rotate* keyword allows specification of the orientation
at which molecules are inserted. The axis of rotation is
determined by the rotation vector (Rx,Ry,Rz) that goes through the
determined by the rotation vector :math:`(R_x,R_y,R_z)` that goes through the
insertion point. The specified *theta* determines the angle of
rotation around that axis. Note that the direction of rotation for
the atoms around the rotation axis is consistent with the right-hand
@ -388,7 +388,7 @@ wrap around the axis in the direction of rotation.
The *radscale* keyword only applies to the *mesh* style and adjusts the
radius of created particles (see above), provided this is supported by
the atom style. Its value is a prefactor (must be > 0.0, default is
the atom style. Its value is a prefactor (must be :math:`>` 0.0, default is
1.0) that is applied to the atom radius inferred from the size of the
individual triangles in the triangle mesh that the particle corresponds
to.
@ -406,12 +406,12 @@ non-overlapping criterion.
.. note::
Checking for overlaps is a costly O(N(N+M)) operation for inserting
*N* new particles into a system with *M* existing particles. This
is because distances to all *M* existing particles are computed for
Checking for overlaps is a costly :math:`\mathcal{O}(N(N+M))` operation for
inserting *N* new particles into a system with *M* existing particles.
This is because distances to all *M* existing particles are computed for
each new particle that is added. Thus the intended use of this
keyword is to add relatively small numbers of particles to systems
which remain at a relatively low density even after the new
that remain at a relatively low density even after the new
particles are created. Careful use of the *maxtry* keyword in
combination with *overlap* is recommended. See the discussion
above about systems with overlapped particles for alternate
@ -422,7 +422,7 @@ the number of attempts to generate valid coordinates for a single new
particle that satisfy all requirements imposed by the *region*, *var*,
and *overlap* keywords. The default is 10 attempts per particle
before the loop over the requested *N* particles advances to the next
particle. Note that if insertion success is unlikely (e.g. inserting
particle. Note that if insertion success is unlikely (e.g., inserting
new particles into a dense system using the *overlap* keyword),
setting the *maxtry* keyword to a large value may result in this
command running for a long time.
@ -447,7 +447,7 @@ Here is an example for the *random* style using these commands
to produce a system as shown in the image with 1520 particles (out of
2000 requested) that are moderately dense and which have no overlaps
sufficient to prevent the LJ pair_style from running properly (because
the overlap criterion = 1.0). The create_atoms command ran for 0.3 s
the overlap criterion is 1.0). The create_atoms command ran for 0.3 s
on a single CPU core.
.. only:: html
@ -460,9 +460,9 @@ The *units* keyword determines the meaning of the distance units used
to specify the coordinates of the one particle created by the *single*
style, or the overlap distance *Doverlap* by the *overlap* keyword. A
*box* value selects standard distance units as defined by the
:doc:`units <units>` command, e.g. Angstroms for units = real or
metal. A *lattice* value means the distance units are in lattice
spacings.
:doc:`units <units>` command (e.g., :math:`\mathrm{\mathring{A}}` for
units = *real* or *metal*\ . A *lattice* value means the distance units are in
lattice spacings.
----------
@ -471,15 +471,15 @@ collection of created atoms are assigned consecutive IDs that start
immediately following the largest atom ID existing before the
create_atoms command was invoked. This is done by the processor's
communicating the number of atoms they each own, the first processor
numbering its atoms from 1 to N1, the second processor from N1+1 to
N2, etc. Where N1 = number of atoms owned by the first processor, N2
= number owned by the second processor, etc. Thus when the same
simulation is performed on different numbers of processors, there is
no guarantee a particular created atom will be assigned the same ID in
both simulations. If molecules are being created, molecule IDs are
assigned to created molecules in a similar fashion.
numbering its atoms from :math:`1` to :math:`N_1`, the second processor from
:math:`N_1+1` to :math:`N_2`, and so on, where :math:`N_1` is the number of
atoms owned by the first processor, :math:`N_2` is the number owned by the
second processor, and so forth. Thus, when the same simulation is performed on
different numbers of processors, there is no guarantee a particular created
atom will be assigned the same ID in both simulations. If molecules are being
created, molecule IDs are assigned to created molecules in a similar fashion.
Aside from their ID, atom type, and xyz position, other properties of
Aside from their ID, atom type, and :math:`xyz` position, other properties of
created atoms are set to default values, depending on which quantities
are defined by the chosen :doc:`atom style <atom_style>`. See the
:doc:`atom style <atom_style>` command for more details. See the
@ -500,17 +500,17 @@ how to change these values.
If molecules are being created, these defaults can be overridden by
values specified in the file read by the :doc:`molecule <molecule>`
command. E.g. the file typically defines bonds (angles,etc) between
command. That is, the file typically defines bonds (angles, etc.) between
atoms in the molecule, and can optionally define charges on each atom.
Note that the *sphere* atom style sets the default particle diameter to
1.0 as well as the density. This means the mass for the particle is not
1.0, but is PI/6 \* diameter\^3 = 0.5236. When using the *mesh* style,
the particle diameter is adjusted from the size of the individual
triangles in the triangle mesh.
1.0, but is :math:`\frac{\pi}{6} d^3 = 0.5236`, where :math:`d` is the
diameter. When using the *mesh* style, the particle diameter is adjusted from
the size of the individual triangles in the triangle mesh.
Note that the *ellipsoid* atom style sets the default particle shape
to (0.0 0.0 0.0) and the density to 1.0 which means it is a point
to (0.0 0.0 0.0) and the density to 1.0, which means it is a point
particle, not an ellipsoid, and has a mass of 1.0.
Note that the *peri* style sets the default volume and density to 1.0
@ -533,8 +533,9 @@ the z-direction for a 2d model.
Related commands
""""""""""""""""
:doc:`lattice <lattice>`, :doc:`region <region>`, :doc:`create_box <create_box>`,
:doc:`read_data <read_data>`, :doc:`read_restart <read_restart>`
:doc:`lattice <lattice>`, :doc:`region <region>`,
:doc:`create_box <create_box>`, :doc:`read_data <read_data>`,
:doc:`read_restart <read_restart>`
Default
"""""""

73
doc/src/create_bonds.rst
View File

@ -67,20 +67,20 @@ the :doc:`bond_style <bond_style>`, :doc:`bond_coeff <bond_coeff>`,
:doc:`dihedral_coeff <dihedral_coeff>`, :doc:`improper_style <improper_style>`,
:doc:`improper_coeff <improper_coeff>` commands.
The *many* style is useful for adding bonds to a system, e.g. between
nearest neighbors in a lattice of atoms, without having to enumerate
The *many* style is useful for adding bonds to a system (e.g., between
nearest neighbors in a lattice of atoms) without having to enumerate
all the bonds in the data file read by the :doc:`read_data <read_data>`
command.
The *single* styles are useful for adding bonds, angles, dihedrals, impropers
to a system incrementally, then continuing a simulation.
The *single* styles are useful for adding bonds, angles, dihedrals, and
impropers to a system incrementally, then continuing a simulation.
Note that this command does not auto-create any angle, dihedral or improper
interactions when a bond is added. Nor does it auto-create any bonds
when an angle, dihedral or improper is added. Or auto-create any angles when a
dihedral or improper is added. Thus the flexibility of this command is limited.
It can be used several times to create different types of bond at
different distances. But it cannot typically auto-create all the
Note that this command does not auto-create any angle, dihedral, or improper
interactions when a bond is added, nor does it auto-create any bonds
when an angle, dihedral, or improper is added. It also will not auto-create
any angles when a dihedral or improper is added. Thus, the flexibility of this
command is limited. It can be used several times to create different types of
bond at different distances, but it cannot typically auto-create all the
bonds or angles or dihedrals or impropers that would normally be defined in a
data file for a complex system of molecules.
@ -88,36 +88,37 @@ data file for a complex system of molecules.
If the system has no bonds (angles, dihedrals, impropers) to begin with,
or if more bonds per atom are being added than currently exist, then you
must insure that the number of bond types and the maximum number of
bonds per atom are set to large enough values. And similarly for
angles, dihedrals and impropers. Otherwise an error may occur when too many
must ensure that the number of bond types and the maximum number of
bonds per atom are set to large enough values, and similarly for
angles, dihedrals, and impropers, otherwise an error may occur when too many
bonds (angles, dihedrals, impropers) are added to an atom. If the
:doc:`read_data <read_data>` command is used to define the system, these
parameters can be set via the "bond types" and "extra bond per atom"
fields in the header section of the data file. If the
:doc:`create_box <create_box>` command is used to define the system,
these 2 parameters can be set via its optional "bond/types" and
"extra/bond/per/atom" arguments. And similarly for angles, dihedrals and
impropers. See the doc pages for these 2 commands for details.
these two parameters can be set via its optional *bond/types* and
*extra/bond/per/atom* arguments, and similarly for angles, dihedrals, and
impropers. See the doc pages for these two commands for details.
----------
The *many* style will create bonds between pairs of atoms I,J where I
is in one of the two specified groups, and J is in the other. The two
groups can be the same, e.g. group "all". The created bonds will be
of bond type *btype*, where *btype* must be a value between 1 and the
The *many* style will create bonds between pairs of atoms :math:`I,J`,
where :math:`I` is in one of the two specified groups and :math:`J` is in the
other. The two groups can be the same (e.g., group "all"). The created bonds
will be of bond type *btype*, where *btype* must be a value between 1 and the
number of bond types defined.
For a bond to be created, an I,J pair of atoms must be a distance D
apart such that *rmin* <= D <= *rmax*\ .
For a bond to be created, an :math:`I,J` pair of atoms must be a distance
:math:`D` apart such that :math:`r_\text{min} \le D \le r_\text{max}`.
The following settings must have been made in an input script before
this style is used:
* special_bonds weight for 1-2 interactions must be 0.0
* special_bonds weight for 1--2 interactions must be 0.0
* a :doc:`pair_style <pair_style>` must be defined
* no :doc:`kspace_style <kspace_style>` defined
* minimum :doc:`pair_style <pair_style>` cutoff + :doc:`neighbor <neighbor>` skin >= *rmax*
* minimum :doc:`pair_style <pair_style>` cutoff + :doc:`neighbor <neighbor>`
skin :math:`\ge r_\text{max}`
These settings are required so that a neighbor list can be created to
search for nearby atoms. Pairs of atoms that are already bonded
@ -127,12 +128,12 @@ a distance that encompasses the *rmax* for new bonds to create.
.. note::
If you want to create bonds between pairs of 1-3 or 1-4 atoms in
If you want to create bonds between pairs of 1--3 or 1--4 atoms in
the current bond topology, then you need to use :doc:`special_bonds
lj 0 1 1 <special_bonds>` to insure those pairs appear in the
neighbor list. They will not appear with the default special_bonds
settings which are zero for 1-2, 1-3, and 1-4 atoms. 1-3 or 1-4
atoms are those which are 2 hops or 3 hops apart in the bond
settings, which are zero for 1--2, 1--3, and 1--4 atoms. 1--3 or 1--4
atoms are those which are two hops or three hops apart in the bond
topology.
An additional requirement for this style is that your system must be
@ -145,7 +146,7 @@ neighbor list requires initialization and setup of a simulation,
similar to what a :doc:`run <run>` command would require.
Note that you can change any of these settings after this command
executes, e.g. if you wish to use long-range Coulombic interactions
executes (e.g., if you wish to use long-range Coulombic interactions)
via the :doc:`kspace_style <kspace_style>` command for your subsequent
simulation.
@ -158,8 +159,8 @@ between 1 and the number of bond types defined.
The *single/angle* style creates a single angle of type *atype*
between three atoms with IDs *aatom1*, *aatom2*, and *aatom3*\ . The
ordering of the atoms is the same as in the *Angles* section of a data
file read by the :doc:`read_data <read_data>` command. I.e. the 3 atoms are
ordered linearly within the angle; the central atom is *aatom2*\ .
file read by the :doc:`read_data <read_data>` command (i.e., the three atoms
are ordered linearly within the angle; the central atom is *aatom2*).
*Atype* must be a value between 1 and the number of angle types
defined.
@ -180,14 +181,14 @@ the number of improper types defined.
----------
The keyword *special* controls whether an internal list of special
bonds is created after one or more bonds, or a single angle, dihedral or
bonds is created after one or more bonds, or a single angle, dihedral, or
improper is added to the system.
The default value is *yes*\ . A value of *no* cannot be used
with the *many* style.
This is an expensive operation since the bond topology for the system
must be walked to find all 1-2, 1-3, 1-4 interactions to store in an
must be walked to find all 1--2, 1--3, and 1--4 interactions to store in an
internal list, which is used when pairwise interactions are weighted;
see the :doc:`special_bonds <special_bonds>` command for details.
@ -204,10 +205,10 @@ bond (or angle, or dihedral, or improper) is added:
create_bonds single/bond 5 17 386 special no
create_bonds single/bond 4 112 183 special yes
Note that you MUST insure the internal list is re-built after the last
bond (angle, dihedral, improper) is added, before performing a simulation.
Otherwise pairwise interactions will not be properly excluded or
weighted. LAMMPS does NOT check that you have done this correctly.
Note that you **must** ensure the internal list is rebuilt after the last
bond (angle, dihedral, improper) is added, *before* performing a simulation.
Otherwise, pairwise interactions will not be properly excluded or
weighted. LAMMPS does **not** check that you have done this correctly.
----------

70
doc/src/create_box.rst
View File

@ -50,28 +50,33 @@ The argument N is the number of atom types that will be used in the
simulation.
If the region is not of style *prism*, then LAMMPS encloses the region
(block, sphere, etc) with an axis-aligned orthogonal bounding box
(block, sphere, etc.) with an axis-aligned orthogonal bounding box
which becomes the simulation domain.
If the region is of style *prism*, LAMMPS creates a non-orthogonal
simulation domain shaped as a parallelepiped with triclinic symmetry.
As defined by the :doc:`region prism <region>` command, the
parallelepiped has its "origin" at (xlo,ylo,zlo) and is defined by 3
edge vectors starting from the origin given by A = (xhi-xlo,0,0); B =
(xy,yhi-ylo,0); C = (xz,yz,zhi-zlo). *Xy,xz,yz* can be 0.0 or
parallelepiped has its "origin" at (xlo,ylo,zlo) and is defined by three
edge vectors starting from the origin given by
:math:`\vec a = (x_\text{hi}-x_\text{lo},0,0)`;
:math:`\vec b = (xy,y_\text{hi}-y_\text{lo},0)`; and
:math:`\vec c = (xz,yz,z_\text{hi}-z_\text{lo})`.
The parameters *xy*\ , *xz*\ , and *yz* can be 0.0 or
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 (xy,xz,yz) that do not skew the box more than half
the distance of the 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
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.
@ -81,18 +86,19 @@ geometric description of triclinic boxes, as defined by LAMMPS, and
how to transform these parameters to and from other commonly used
triclinic representations.
When a prism region is used, the simulation domain should normally be
periodic in the dimension that the tilt is applied to, which is given
by the second dimension of the tilt factor (e.g. y for xy tilt). This
is so that pairs of atoms interacting across that boundary will have
one of them shifted by the tilt factor. Periodicity is set by the
:doc:`boundary <boundary>` command. For example, if the xy tilt factor
is non-zero, then the y dimension should be periodic. Similarly, the
z dimension should be periodic if xz or yz is non-zero. LAMMPS does
not require this periodicity, but you may lose atoms if this is not
When a prism region is used, the simulation domain should normally be periodic
in the dimension that the tilt is applied to, which is given by the second
dimension of the tilt factor (e.g., :math:`y` for :math:`xy` tilt). This is so
that pairs of atoms interacting across that boundary will have one of them
shifted by the tilt factor. Periodicity is set by the
:doc:`boundary <boundary>` command. For example, if the :math:`xy` tilt factor
is non-zero, then the :math:`y` dimension should be periodic. Similarly, the
:math:`z` dimension should be periodic if :math:`xz` or :math:`yz` is non-zero.
LAMMPS does not require this periodicity, but you may lose atoms if this is not
the case.
Also note that if your simulation will tilt the box, e.g. via the :doc:`fix deform <fix_deform>` command, the simulation box must be setup to
Note that if your simulation will tilt the box (e.g., via the
:doc:`fix deform <fix_deform>` command), the simulation box must be set up to
be triclinic, even if the tilt factors are initially 0.0. You can
also change an orthogonal box to a triclinic box or vice versa by
using the :doc:`change box <change_box>` command with its *ortho* and
@ -103,11 +109,11 @@ using the :doc:`change box <change_box>` command with its *ortho* and
If the system is non-periodic (in a dimension), then you should
not make the lo/hi box dimensions (as defined in your
:doc:`region <region>` command) radically smaller/larger than the extent
of the atoms you eventually plan to create, e.g. via the
:doc:`create_atoms <create_atoms>` command. For example, if your atoms
extend from 0 to 50, you should not specify the box bounds as -10000
and 10000. This is because as described above, LAMMPS uses the
specified box size to layout the 3d grid of processors. A huge
of the atoms you eventually plan to create (e.g., via the
:doc:`create_atoms <create_atoms>` command). For example, if your atoms
extend from 0 to 50, you should not specify the box bounds as :math:`-10000`
and :math:`10000`. This is because as described above, LAMMPS uses the
specified box size to lay out the 3d grid of processors. A huge
(mostly empty) box will be sub-optimal for performance when using
"fixed" boundary conditions (see the :doc:`boundary <boundary>`
command). When using "shrink-wrap" boundary conditions (see the
@ -119,23 +125,25 @@ using the :doc:`change box <change_box>` command with its *ortho* and
The optional keywords can be used to create a system that allows for
bond (angle, dihedral, improper) interactions, or for molecules with
special 1-2,1-3,1-4 neighbors to be added later. These optional
special 1--2, 1--3, or 1--4 neighbors to be added later. These optional
keywords serve the same purpose as the analogous keywords that can be
used in a data file which are recognized by the
:doc:`read_data <read_data>` command when it sets up a system.
Note that if these keywords are not used, then the create_box command
creates an atomic (non-molecular) simulation that does not allow bonds
between pairs of atoms to be defined, or a :doc:`bond potential <bond_style>` to be specified, or for molecules with
between pairs of atoms to be defined, or a
:doc:`bond potential <bond_style>` to be specified, or for molecules with
special neighbors to be added to the system by commands such as
:doc:`create_atoms mol <create_atoms>`, :doc:`fix deposit <fix_deposit>`
or :doc:`fix pour <fix_pour>`.
As an example, see the examples/deposit/in.deposit.molecule script,
which deposits molecules onto a substrate. Initially there are no
molecules in the system, but they are added later by the :doc:`fix deposit <fix_deposit>` command. The create_box command in the
molecules in the system, but they are added later by the
:doc:`fix deposit <fix_deposit>` command. The create_box command in the
script uses the bond/types and extra/bond/per/atom keywords to allow
this. If the added molecule contained more than 1 special bond
this. If the added molecule contained more than one special bond
(allowed by default), an extra/special/per/atom keyword would also
need to be specified.

18
doc/src/delete_atoms.rst
View File

@ -62,7 +62,7 @@ Description
Delete the specified atoms. This command can be used, for example, to
carve out voids from a block of material or to delete created atoms
that are too close to each other (e.g. at a grain boundary).
that are too close to each other (e.g., at a grain boundary).
For style *group*, all atoms belonging to the group are deleted.
@ -78,7 +78,7 @@ first group specified and the other atom is in the second group are
considered. The atom that is in the first group is the one that is
deleted.
Note that it is OK for the two group IDs to be the same (e.g. group
Note that it is OK for the two group IDs to be the same (e.g., group
*all*\ ), or for some atoms to be members of both groups. In these
cases, either atom in the pair may be deleted. Also note that if
there are atoms which are members of both groups, the only guarantee
@ -147,7 +147,7 @@ interactions, is one where the topology of the interactions is
typically defined in the data file read by the :doc:`read_data
<read_data>` command, and where the interactions themselves are
defined with the :doc:`bond_style <bond_style>`, :doc:`angle_style
<angle_style>`, etc commands. If you delete atoms from such a system,
<angle_style>`, etc. commands. If you delete atoms from such a system,
you must be careful not to end up with bonded interactions that are
stored by remaining atoms but which include deleted atoms. This will
cause LAMMPS to generate a "missing atoms" error when the bonded
@ -158,7 +158,7 @@ It the *bond* keyword is set to *yes* then any bond or angle or
dihedral or improper interaction that includes a deleted atom is also
removed from the lists of such interactions stored by non-deleted
atoms. Note that simply deleting interactions due to dangling bonds
(e.g. at a surface) may result in a inaccurate or invalid model for
(e.g., at a surface) may result in a inaccurate or invalid model for
the remaining atoms.
It the *mol* keyword is set to *yes*, then for every atom that is
@ -182,17 +182,17 @@ Restrictions
The *overlap* styles requires inter-processor communication to acquire
ghost atoms and build a neighbor list. This means that your system
must be ready to perform a simulation before using this command (force
fields setup, atom masses set, etc). Since a neighbor list is used to
fields setup, atom masses set, etc.). Since a neighbor list is used to
find overlapping atom pairs, it also means that you must define a
:doc:`pair style <pair_style>` with the minimum force cutoff distance
between any pair of atoms types (plus the :doc:`neighbor <neighbor>`
skin) >= the specified overlap cutoff.
skin) :math:`\ge` the specified overlap cutoff.
If the :doc:`special_bonds <special_bonds>` command is used with a
setting of 0, then a pair of bonded atoms (1-2, 1-3, or 1-4) will not
setting of 0, then a pair of bonded atoms (1--2, 1--3, or 1--4) will not
appear in the neighbor list, and thus will not be considered for
deletion by the *overlap* styles. You probably don't want to be
deleting one atom in a bonded pair anyway.
deletion by the *overlap* styles. You probably do not want to
delete one atom in a bonded pair anyway.
The *bond yes* option cannot be used with molecular systems defined
using molecule template files via the :doc:`molecule <molecule>` and

60
doc/src/delete_bonds.rst
View File

@ -39,8 +39,8 @@ Examples
Description
"""""""""""
Turn off (or on) molecular topology interactions, i.e. bonds, angles,
dihedrals, impropers. This command is useful for deleting
Turn off (or on) molecular topology interactions (i.e., bonds, angles,
dihedrals, and/or impropers). This command is useful for deleting
interactions that have been previously turned off by bond-breaking
potentials. It is also useful for turning off topology interactions
between frozen or rigid atoms. Pairwise interactions can be turned
@ -54,15 +54,15 @@ keyword to change the behavior.
Several of the styles (\ *atom*, *bond*, *angle*, *dihedral*,
*improper*\ ) take a *type* as an argument. The specified *type* should
be an integer from 0 to N, where N is the number of relevant types
(atom types, bond types, etc). A value of 0 is only relevant for
be an integer from 0 to :math:`N`, where :math:`N` is the number of relevant
types (atom types, bond types, etc.). A value of 0 is only relevant for
style *bond*\ ; see details below. In all cases, a wildcard asterisk
can be used in place of or in conjunction with the *type* argument to
specify a range of types. This takes the form "\*" or "\*n" or "n\*" or
"m\*n". If N = the number of types, then an asterisk with no numeric
values means all types from 0 to N. A leading asterisk means all
specify a range of types. This takes the form "\*" or "\*n" or "m\*" or
"m\*n". If :math:`N` is the number of types, then an asterisk with no numeric
values means all types from 0 to :math:`N`. A leading asterisk means all
types from 0 to n (inclusive). A trailing asterisk means all types
from n to N (inclusive). A middle asterisk means all types from m to
from m to N (inclusive). A middle asterisk means all types from m to
n (inclusive). Note that it is fine to include a type of 0 for
non-bond styles; it will simply be ignored.
@ -79,7 +79,8 @@ must also be of the specified type. Styles *angle*, *dihedral*, and
For style *bond*, you can set the type to 0 to delete bonds that have
been previously broken by a bond-breaking potential (which sets the
bond type to 0 when a bond is broken); e.g. see the :doc:`bond_style quartic <bond_style>` command.
bond type to 0 when a bond is broken); for example, see the
:doc:`bond_style quartic <bond_style>` command.
For style *stats* no interactions are turned off (or on); the status
of all interactions in the specified group is simply reported. This
@ -88,19 +89,19 @@ bond-breaking potential during a previous run.
The default behavior of the delete_bonds command is to turn off
interactions by toggling their type to a negative value, but not to
permanently remove the interaction. E.g. a bond_type of 2 is set to
-2. The neighbor list creation routines will not include such an
permanently remove the interaction. For example, a bond_type of 2 is set to
:math:`-2.` The neighbor list creation routines will not include such an
interaction in their interaction lists. The default is also to not
alter the list of 1-2, 1-3, 1-4 neighbors computed by the
alter the list of 1--2, 1--3, or 1--4 neighbors computed by the
:doc:`special_bonds <special_bonds>` command and used to weight pairwise
force and energy calculations. This means that pairwise computations
will proceed as if the bond (or angle, etc) were still turned on.
will proceed as if the bond (or angle, etc.) were still turned on.
Several keywords can be appended to the argument list to alter the
default behaviors.
The *any* keyword changes the requirement that all atoms in the bond
(angle, etc) must be in the specified group in order to turn-off the
(angle, etc) must be in the specified group in order to turn off the
interaction. Instead, if any of the atoms in the interaction are in
the specified group, it will be turned off (or on if the *undo*
keyword is used).
@ -109,42 +110,43 @@ The *undo* keyword inverts the delete_bonds command so that the
specified bonds, angles, etc are turned on if they are currently
turned off. This means a negative value is toggled to positive. For
example, for style *angle*, if *type* is specified as 2, then all
angles with current type = -2, are reset to type = 2. Note that the
:doc:`fix shake <fix_shake>` command also sets bond and angle types
negative, so this option should not be used on those interactions.
angles with current type = :math:`-2` are reset to type = :math:`2`.
Note that the :doc:`fix shake <fix_shake>` command also sets bond and angle
types negative, so this option should not be used on those interactions.
The *remove* keyword is invoked at the end of the delete_bonds
operation. It causes turned-off bonds (angles, etc) to be removed
operation. It causes turned-off bonds (angles, etc.) to be removed
from each atom's data structure and then adjusts the global bond
(angle, etc) counts accordingly. Removal is a permanent change;
(angle, etc.) counts accordingly. Removal is a permanent change;
removed bonds cannot be turned back on via the *undo* keyword.
Removal does not alter the pairwise 1-2, 1-3, 1-4 weighting list.
Removal does not alter the pairwise 1--2, 1--3, or 1--4 weighting list.
The *special* keyword is invoked at the end of the delete_bonds
operation, after (optional) removal. It re-computes the pairwise 1-2,
1-3, 1-4 weighting list. The weighting list computation treats
operation, after (optional) removal. It re-computes the pairwise 1--2,
1--3, 1--4 weighting list. The weighting list computation treats
turned-off bonds the same as turned-on. Thus, turned-off bonds must
be removed if you wish to change the weighting list.
Note that the choice of *remove* and *special* options affects how
1-2, 1-3, 1-4 pairwise interactions will be computed across bonds that
1--2, 1--3, 1--4 pairwise interactions will be computed across bonds that
have been modified by the delete_bonds command.
Restrictions
""""""""""""
This command requires inter-processor communication to acquire ghost
atoms, to coordinate the deleting of bonds, angles, etc between atoms
atoms, to coordinate the deleting of bonds, angles, etc. between atoms
shared by multiple processors. This means that your system must be
ready to perform a simulation before using this command (force fields
setup, atom masses set, etc). Just as would be needed to run
setup, atom masses set, etc.). Just as would be needed to run
dynamics, the force field you define should define a cutoff
(e.g. through a :doc:`pair_style <pair_style>` command) which is long
(e.g., through a :doc:`pair_style <pair_style>` command) which is long
enough for a processor to acquire the ghost atoms its needs to compute
bond, angle, etc interactions.
bond, angle, etc. interactions.
If deleted bonds (angles, etc) are removed but the 1-2, 1-3, 1-4
weighting list is not re-computed, this can cause a later :doc:`fix shake <fix_shake>` command to fail due to an atom's bonds being
If deleted bonds (or angles, etc.) are removed but the 1--2, 1--3, and 1--4
weighting list is not recomputed, this can cause a later
:doc:`fix shake <fix_shake>` command to fail due to an atom's bonds being
inconsistent with the weighting list. This should only happen if the
group used in the fix command includes both atoms in the bond, in
which case you probably should be recomputing the weighting list.

6
doc/src/dielectric.rst
View File

@ -6,7 +6,7 @@ dielectric command
Syntax
""""""
.. parsed-literal::
.. code-block:: LAMMPS
dielectric value
@ -25,9 +25,9 @@ Description
Set the dielectric constant for Coulombic interactions (pairwise and
long-range) to this value. The constant is unitless, since it is used
to reduce the strength of the interactions. The value is used in the
denominator of the formulas for Coulombic interactions - e.g. a value
denominator of the formulas for Coulombic interactions (e.g., a value
of 4.0 reduces the Coulombic interactions to 25% of their default
strength. See the :doc:`pair_style <pair_style>` command for more
strength). See the :doc:`pair_style <pair_style>` command for more
details.
Restrictions

20
doc/src/dihedral_coeff.rst
View File

@ -33,10 +33,10 @@ Dihedral coefficients can also be set in the data file read by the
N can be specified in one of two ways. An explicit numeric value can
be used, as in the first example above. Or a wild-card asterisk can be
used to set the coefficients for multiple dihedral types. This takes the
form "\*" or "\*n" or "n\*" or "m\*n". If N = the number of dihedral types,
then an asterisk with no numeric values means all types from 1 to N. A
leading asterisk means all types from 1 to n (inclusive). A trailing
asterisk means all types from n to N (inclusive). A middle asterisk
form "\*" or "\*n" or "m\*" or "m\*n". If :math:`N` is the number of dihedral
types, then an asterisk with no numeric values means all types from 1 to
:math:`N`. A leading asterisk means all types from 1 to n (inclusive). A
trailing asterisk means all types from m to N (inclusive). A middle asterisk
means all types from m to n (inclusive).
Note that using a dihedral_coeff command can override a previous setting
@ -51,7 +51,7 @@ for all dihedral types, then overwrite the coeffs for just dihedral type 2:
A line in a data file that specifies dihedral coefficients uses the exact
same format as the arguments of the dihedral_coeff command in an input
script, except that wild-card asterisks should not be used since
coefficients for all N types must be listed in the file. For example,
coefficients for all :math:`N` types must be listed in the file. For example,
under the "Dihedral Coeffs" section of a data file, the line that
corresponds to the first example above would be listed as
@ -69,11 +69,11 @@ page for details.
When comparing the formulas and coefficients for various LAMMPS
dihedral styles with dihedral equations defined by other force fields,
note that some force field implementations divide/multiply the energy
prefactor *K* by the multiple number of torsions that contain the J-K
bond in an I-J-K-L torsion. LAMMPS does not do this, i.e. the listed
dihedral equation applies to each individual dihedral. Thus you need
to define *K* appropriately to account for this difference if
necessary.
prefactor *K* by the multiple number of torsions that contain the
*J*\ --\ *K* bond in an *I*\ -\ *J*\ -\ *K*\ -\ *L* torsion. LAMMPS does
not do this (i.e., the listed dihedral equation applies to each individual
dihedral). Thus, you need to define *K* appropriately to account for this
difference, if necessary.
----------

19
doc/src/dihedral_style.rst
View File

@ -51,7 +51,7 @@ to be re-specified.
When both a dihedral and pair style is defined, the
:doc:`special_bonds <special_bonds>` command often needs to be used to
turn off (or weight) the pairwise interaction that would otherwise
exist between 4 bonded atoms.
exist between four bonded atoms.
In the formulas listed for each dihedral style, *phi* is the torsional
angle defined by the quadruplet of atoms. This angle has a sign
@ -60,11 +60,11 @@ convention as shown in this diagram:
.. image:: JPG/dihedral_sign.jpg
:align: center
where the I,J,K,L ordering of the 4 atoms that define the dihedral
where the :math:`I,J,K,L` ordering of the four atoms that define the dihedral
is from left to right.
This sign convention effects several of the dihedral styles listed
below (e.g. charmm, helix) in the sense that the energy formula
below (e.g., charmm, helix) in the sense that the energy formula
depends on the sign of phi, which may be reflected in the value of the
coefficients you specify.
@ -73,10 +73,10 @@ coefficients you specify.
When comparing the formulas and coefficients for various LAMMPS
dihedral styles with dihedral equations defined by other force fields,
note that some force field implementations divide/multiply the energy
prefactor *K* by the multiple number of torsions that contain the J-K
bond in an I-J-K-L torsion. LAMMPS does not do this, i.e. the listed
dihedral equation applies to each individual dihedral. Thus you need
to define *K* appropriately via the
prefactor *K* by the multiple number of torsions that contain the
*J*\ --\ *K* bond in an *I*\ --\ *J*\ --\ *K*\ --\ *L* torsion. LAMMPS does
not do this (i.e., the listed dihedral equation applies to each individual
dihedral). Thus, you need to define *K* appropriately via the
:doc:`dihedral_coeff <dihedral_coeff>` command to account for this
difference if necessary.
@ -93,8 +93,9 @@ command.
There are also additional accelerated pair styles included in the
LAMMPS distribution for faster performance on CPUs, GPUs, and KNLs.
The individual style names on the :ref:`Commands dihedral <dihedral>` page are followed by one or
more of (g,i,k,o,t) to indicate which accelerated styles exist.
The individual style names on the :ref:`Commands dihedral <dihedral>` page are
followed by one or more of (g,i,k,o,t) to indicate which accelerated styles
exist.
* :doc:`none <dihedral_none>` - turn off dihedral interactions
* :doc:`zero <dihedral_zero>` - topology but no interactions

2
doc/src/dimension.rst
View File

@ -6,7 +6,7 @@ dimension command
Syntax
""""""
.. parsed-literal::
.. code-block:: LAMMPS
dimension N

30
doc/src/displace_atoms.rst
View File

@ -56,7 +56,7 @@ can be imposed on the system. Or two groups of atoms can be brought
into closer proximity.
The *move* style displaces the group of atoms by the specified 3d
displacement vector. Any of the 3 quantities defining the vector
displacement vector. Any of the three quantities defining the vector
components can be specified as an equal-style or atom-style
:doc:`variable <variable>`. If the value is a variable, it should be
specified as v_name, where name is the variable name. In this case,
@ -78,20 +78,20 @@ doc page for more details.
The *ramp* style displaces atoms a variable amount in one dimension
depending on the atom's coordinate in a (possibly) different
dimension. For example, the second example command displaces atoms in
the x-direction an amount between 0.0 and 5.0 distance units. Each
atom's displacement depends on the fractional distance its y
coordinate is between 2.0 and 20.5. Atoms with y-coordinates outside
the *x*\ -direction an amount between 0.0 and 5.0 distance units. Each
atom's displacement depends on the fractional distance its *y*
coordinate is between 2.0 and 20.5. Atoms with *y*\ -coordinates outside
those bounds will be moved the minimum (0.0) or maximum (5.0) amount.
The *random* style independently moves each atom in the group by a
random displacement, uniformly sampled from a value between -dx and
+dx in the x dimension, and similarly for y and z. Random numbers are
used in such a way that the displacement of a particular atom is the
same, regardless of how many processors are being used.
random displacement, uniformly sampled from a value between :math:`-dx` and
:math:`+dx` in the *x* dimension, and similarly for *y* and *z*.
Random numbers are used in such a way that the displacement of a particular
atom is the same, regardless of how many processors are being used.
The *rotate* style rotates each atom in the group by the angle *theta*
around a rotation axis *R* = (Rx,Ry,Rz) that goes through a point *P* =
(Px,Py,Pz). The direction of rotation for the atoms around the
around a rotation axis :math:`R = (R_x,R_y,R_z)` that goes through a point
:math:`P = (P_x,P_y,P_z)`. The direction of rotation for the atoms around the
rotation axis is consistent with the right-hand rule: if your
right-hand thumb points along *R*, then your fingers wrap around the
axis in the direction of positive theta.
@ -104,10 +104,10 @@ atom's rotation.
Distance units for displacements and the origin point of the *rotate*
style are determined by the setting of *box* or *lattice* for the
*units* keyword. *Box* means distance units as defined by the
:doc:`units <units>` command - e.g. Angstroms for *real* units.
*Lattice* means distance units are in lattice spacings. The
:doc:`lattice <lattice>` command must have been previously used to
define the lattice spacing.
:doc:`units <units>` command (e.g., :math:`\mathrm{\mathring A}` for
*real* or *metal* units). *Lattice* means distance units are in lattice
spacings. The :doc:`lattice <lattice>` command must have been previously used
to define the lattice spacing.
----------
@ -139,7 +139,7 @@ Restrictions
""""""""""""
For a 2d simulation, only rotations around the a vector parallel to
the z-axis are allowed.
the :math:`z`-axis are allowed.
Related commands
""""""""""""""""

251
doc/src/dump.rst
View File

@ -176,10 +176,10 @@ Examples
Description
"""""""""""
Dump a snapshot of atom quantities to one or more files every N
Dump a snapshot of atom quantities to one or more files every :math:`N`
timesteps in one of several styles. The *image* and *movie* styles are
the exception: the *image* style renders a JPG, PNG, or PPM image file
of the atom configuration every N timesteps while the *movie* style
of the atom configuration every :math:`N` timesteps while the *movie* style
combines and compresses them into a movie file; both are discussed in
detail on the :doc:`dump image <dump_image>` page. The timesteps on
which dump output is written can also be controlled by a variable.
@ -188,8 +188,7 @@ See the :doc:`dump_modify every <dump_modify>` command.
Only information for atoms in the specified group is dumped. The
:doc:`dump_modify thresh and region and refresh <dump_modify>` commands
can also alter what atoms are included. Not all styles support
these options; see details on the :doc:`dump_modify <dump_modify>` doc
page.
these options; see details on the :doc:`dump_modify <dump_modify>` doc page.
As described below, the filename determines the kind of output (text
or binary or gzipped, one big file or one per timestep, one big file
@ -231,7 +230,7 @@ by the regular dump styles, which may be required on clusters where
the interface to the high-speed network disallows using the fork()
library call (which is needed for a pipe). For the remainder of this
page, you should thus consider the *atom* and *atom/gz* styles
(etc) to be inter-changeable, with the exception of the required
(etc.) to be inter-changeable, with the exception of the required
filename suffix.
Similarly, the *atom/zstd*, *cfg/zstd*, *custom/zstd*, *local/zstd*,
@ -243,9 +242,9 @@ the compression level in both variants.
As explained below, the *atom/mpiio*, *cfg/mpiio*, *custom/mpiio*, and
*xyz/mpiio* styles are identical in command syntax and in the format
of the dump files they create, to the corresponding styles without
"mpiio", except the single dump file they produce is written in
"mpiio," except the single dump file they produce is written in
parallel via the MPI-IO library. For the remainder of this page,
you should thus consider the *atom* and *atom/mpiio* styles (etc) to
you should thus consider the *atom* and *atom/mpiio* styles (etc.) to
be inter-changeable. The one exception is how the filename is
specified for the MPI-IO styles, as explained below.
@ -285,16 +284,16 @@ For an orthogonal simulation box this information is formatted as:
zlo zhi
where xlo,xhi are the maximum extents of the simulation box in the
x-dimension, and similarly for y and z. The "xx yy zz" represent 6
characters that encode the style of boundary for each of the 6
simulation box boundaries (xlo,xhi and ylo,yhi and zlo,zhi). Each of
the 6 characters is either p = periodic, f = fixed, s = shrink wrap,
or m = shrink wrapped with a minimum value. See the
:math:`x`-dimension, and similarly for :math:`y` and :math:`z`. The
"xx yy zz" terms are six characters that encode the style of boundary for each
of the sisx simulation box boundaries (xlo,xhi; ylo,yhi; and zlo,zhi). Each of
the six characters is either 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 3 tilt factors (xy, xz, yz) of the triclinic box,
along with the 3 tilt factors (*xy*, *xz*, *yz*) of the triclinic box,
formatted as follows:
.. parsed-literal::
@ -305,15 +304,15 @@ formatted as follows:
zlo_bound zhi_bound yz
The presence of the text "xy xz yz" in the ITEM line indicates that
the 3 tilt factors will be included on each of the 3 following lines.
the three tilt factors will be included on each of the three following lines.
This bounding box is convenient for many visualization programs. The
meaning of the 6 character flags for "xx yy zz" is the same as above.
meaning of the six character flags for "xx yy zz" is the same as above.
Note that the first two numbers on each line are now xlo_bound instead
of xlo, etc, since they represent a bounding box. See the :doc:`Howto
of xlo, etc. because they represent a bounding box. See the :doc:`Howto
triclinic <Howto_triclinic>` page for a geometric description of
triclinic boxes, as defined by LAMMPS, simple formulas for how the 6
bounding box extents (xlo_bound,xhi_bound,etc) are calculated from the
triclinic boxes, as defined by LAMMPS, simple formulas for how the six
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.
@ -324,8 +323,8 @@ attributes you specify in the dump command for the *custom* style.
For style *atom*, atom coordinates are written to the file, along with
the atom ID and atom type. By default, atom coords are written in a
scaled format (from 0 to 1). I.e. an x value of 0.25 means the atom
is at a location 1/4 of the distance from xlo to xhi of the box
scaled format (from 0 to 1). That is, an :math:`x` value of 0.25 means the
atom is at a location 1/4 of the distance from *xlo* to *xhi* of the box
boundaries. The format can be changed to unscaled coords via the
:doc:`dump_modify <dump_modify>` settings. Image flags can also be
added for each atom via dump_modify.
@ -344,11 +343,11 @@ For style *local*, local output generated by :doc:`computes <compute>`
and :doc:`fixes <fix>` is used to generate lines of output that is
written to the dump file. This local data is typically calculated by
each processor based on the atoms it owns, but there may be zero or
more entities per atom, e.g. a list of bond distances. An explanation
more entities per atom (e.g., a list of bond distances). An explanation
of the possible dump local attributes is given below. Note that by
using input from the :doc:`compute property/local
<compute_property_local>` command with dump local, it is possible to
generate information on bonds, angles, etc that can be cut and pasted
generate information on bonds, angles, etc. that can be cut and pasted
directly into a data file read by the :doc:`read_data <read_data>`
command.
@ -408,18 +407,17 @@ The *xyz* style writes XYZ files, which is a simple text-based
coordinate format that many codes can read. Specifically it has
a line with the number of atoms, then a comment line that is
usually ignored followed by one line per atom with the atom type
and the x-, y-, and z-coordinate of that atom. You can use the
:doc:`dump_modify element <dump_modify>` option to change the output
from using the (numerical) atom type to an element name (or some
other label). This will help many visualization programs to guess
bonds and colors.
and the :math:`x`-, :math:`y`-, and :math:`z`-coordinate of that atom.
You can use the :doc:`dump_modify element <dump_modify>` option to change the
output from using the (numerical) atom type to an element name (or some other
label). This will help many visualization programs to guess bonds and colors.
.. versionadded:: 4May2022
Dump style *yaml* has the same command syntax as style *custom* and
writes YAML format files that can be easily parsed by a variety of data
processing tools and programming languages. Each timestep will be
written as a YAML "document" (i.e. starts with "---" and ends with
written as a YAML "document" (i.e., starts with "---" and ends with
"..."). The style supports writing one file per timestep through the
"\*" wildcard but not multi-processor outputs with the "%" token in the
filename. In addition to per-atom data, :doc:`thermo <thermo>` data can
@ -435,14 +433,14 @@ Below is an example for a YAML format dump created by the following commands.
dump out all yaml 100 dump.yaml id type x y z vx vy vz ix iy iz
dump_modify out time yes units yes thermo yes format 1 %5d format "% 10.6e"
The tags "time", "units", and "thermo" are optional and enabled by the
dump_modify command. The list under the "box" tag has 3 lines for
orthogonal boxes and 4 lines with triclinic boxes, where the first 3 are
the box boundaries and the 4th the three tilt factors (xy, xz, yz). The
"thermo" data follows the format of the *yaml* thermo style. The
"keywords" tag lists the per-atom properties contained in the "data"
columns, which contain a list with one line per atom. The keywords may
be renamed using the dump_modify command same as for the *custom* dump
The tags "time," "units," and "thermo" are optional and enabled by the
dump_modify command. The list under the "box" tag has three lines for
orthogonal boxes and four lines for triclinic boxes, where the first three are
the box boundaries and the fourth the three tilt factors (:math:`xy`,
:math:`xz`, :math:`yz`). The "thermo" data follows the format of the *yaml*
thermo style. The "keywords" tag lists the per-atom properties contained in
the "data" columns, which contain a list with one line per atom. The keywords
may be renamed using the dump_modify command same as for the *custom* dump
style.
.. code-block:: yaml
@ -487,14 +485,14 @@ popular molecular viewing program.
----------
Dumps are performed on timesteps that are a multiple of N (including
Dumps are performed on timesteps that are a multiple of :math:`N` (including
timestep 0) and on the last timestep of a minimization if the
minimization converges. Note that this means a dump will not be
performed on the initial timestep after the dump command is invoked,
if the current timestep is not a multiple of N. This behavior can be
if the current timestep is not a multiple of :math:`N`. This behavior can be
changed via the :doc:`dump_modify first <dump_modify>` command, which
can also be useful if the dump command is invoked after a minimization
ended on an arbitrary timestep. N can be changed between runs by
ended on an arbitrary timestep. :math:`N` can be changed between runs by
using the :doc:`dump_modify every <dump_modify>` command (not allowed
for *dcd* style). The :doc:`dump_modify every <dump_modify>` command
also allows a variable to be used to determine the sequence of
@ -515,19 +513,19 @@ For example, tmp.dump.\* becomes tmp.dump.0, tmp.dump.10000,
tmp.dump.20000, etc. This option is not available for the *dcd* and
*xtc* styles. Note that the :doc:`dump_modify pad <dump_modify>`
command can be used to insure all timestep numbers are the same length
(e.g. 00010), which can make it easier to read a series of dump files
(e.g., 00010), which can make it easier to read a series of dump files
in order with some post-processing tools.
If a "%" character appears in the filename, then each of P processors
writes a portion of the dump file, and the "%" character is replaced
with the processor ID from 0 to P-1. For example, tmp.dump.% becomes
tmp.dump.0, tmp.dump.1, ... tmp.dump.P-1, etc. This creates smaller
files and can be a fast mode of output on parallel machines that support
parallel I/O for output. This option is **not** available for the *dcd*,
*xtc*, *xyz*, and *yaml* styles.
with the processor ID from :math:`0` to :math:`P-1`. For example, tmp.dump.%
becomes tmp.dump.0, tmp.dump.1, ... tmp.dump.:math:`P-1`, etc. This creates
smaller files and can be a fast mode of output on parallel machines that
support parallel I/O for output. This option is **not** available for the
*dcd*, *xtc*, *xyz*, and *yaml* styles.
By default, P = the number of processors meaning one file per
processor, but P can be set to a smaller value via the *nfile* or
By default, :math:`P` is the the number of processors, meaning one file per
processor, but :math:`P` can be set to a smaller value via the *nfile* or
*fileper* keywords of the :doc:`dump_modify <dump_modify>` command.
These options can be the most efficient way of writing out dump files
when running on large numbers of processors.
@ -539,15 +537,15 @@ For the *atom/mpiio*, *cfg/mpiio*, *custom/mpiio*, and *xyz/mpiio*
styles, a single dump file is written in parallel via the MPI-IO
library, which is part of the MPI standard for versions 2.0 and above.
Using MPI-IO requires two steps. First, build LAMMPS with its MPIIO
package installed, e.g.
package installed, viz.,
.. code-block:: bash
make yes-mpiio # installs the MPIIO package
make mpi # build LAMMPS for your platform
Second, use a dump filename which contains ".mpiio". Note that it
does not have to end in ".mpiio", just contain those characters.
Second, use a dump filename which contains ".mpiio." Note that it
does not have to end in ".mpiio," just contain those characters.
Unlike MPI-IO restart files, which must be both written and read using
MPI-IO, the dump files produced by these MPI-IO styles are identical
in format to the files produced by their non-MPI-IO style
@ -564,42 +562,41 @@ MPI-IO.
Note that MPI-IO dump files are one large file which all processors
write to. You thus cannot use the "%" wildcard character described
above in the filename since that specifies generation of multiple
files. You can use the ".bin" or ".lammpsbin" suffix described below in an MPI-IO
dump file; again this file will be written in parallel and have the
files. You can use the ".bin" or ".lammpsbin" suffix described below in an
MPI-IO dump file; again this file will be written in parallel and have the
same binary format as if it were written without MPI-IO.
If the filename ends with ".bin" or ".lammpsbin", the dump file (or files, if "\*" or
"%" is also used) is written in binary format. A binary dump file
If the filename ends with ".bin" or ".lammpsbin", the dump file (or files, if
"\*" or "%" is also used) is written in binary format. A binary dump file
will be about the same size as a text version, but will typically
write out much faster. Of course, when post-processing, you will need
to convert it back to text format (see the :ref:`binary2txt tool <binary>`) or write your own code to read the binary
file. The format of the binary file can be understood by looking at
the tools/binary2txt.cpp file. This option is only available for the
*atom* and *custom* styles.
to convert it back to text format (see the :ref:`binary2txt tool <binary>`) or
write your own code to read the binary file. The format of the binary file can
be understood by looking at the :file:`tools/binary2txt.cpp` file. This option
is only available for the *atom* and *custom* styles.
If the filename ends with ".gz", the dump file (or files, if "\*" or "%"
is also used) is written in gzipped format. A gzipped dump file will
be about 3x smaller than the text version, but will also take longer
to write. This option is not available for the *dcd* and *xtc*
styles.
is also used) is written in gzipped format. A gzipped dump file will be about
:math:`3\times` smaller than the text version, but will also take longer
to write. This option is not available for the *dcd* and *xtc* styles.
----------
Note that in the discussion which follows, for styles which can
reference values from a compute or fix or custom atom property, like
the *custom*\ , *cfg*\ , or *local* styles, the bracketed index I can
the *custom*\ , *cfg*\ , or *local* styles, the bracketed index :math:`i` can
be specified using a wildcard asterisk with the index to effectively
specify multiple values. This takes the form "\*" or "\*n" or "n\*"
or "m\*n". If N = the number of columns in the array, then an
asterisk with no numeric values means all column indices from 1 to N.
specify multiple values. This takes the form "\*" or "\*n" or "m\*"
or "m\*n." If :math:`N` is the number of columns in the array, then an
asterisk with no numeric values means all column indices from 1 to :math:`N`.
A leading asterisk means all indices from 1 to n (inclusive). A
trailing asterisk means all indices from n to N (inclusive). A middle
trailing asterisk means all indices from m to :math:`N` (inclusive). A middle
asterisk means all indices from m to n (inclusive).
Using a wildcard is the same as if the individual columns of the array
had been listed one by one. E.g. these 2 dump commands are
had been listed one by one. For example, these two dump commands are
equivalent, since the :doc:`compute stress/atom <compute_stress_atom>`
command creates a per-atom array with 6 columns:
command creates a per-atom array with six columns:
.. code-block:: LAMMPS
@ -614,13 +611,12 @@ This section explains the local attributes that can be specified as
part of the *local* style.
The *index* attribute can be used to generate an index number from 1
to N for each line written into the dump file, where N is the total
number of local datums from all processors, or lines of output that
to :math:`N` for each line written into the dump file, where :math:`N` is the
total number of local datums from all processors, or lines of output that
will appear in the snapshot. Note that because data from different
processors depend on what atoms they currently own, and atoms migrate
between processor, there is no guarantee that the same index will be
used for the same info (e.g. a particular bond) in successive
snapshots.
used for the same info (e.g., a particular bond) in successive snapshots.
The *c_ID* and *c_ID[I]* attributes allow local vectors or arrays
calculated by a :doc:`compute <compute>` to be output. The ID in the
@ -637,10 +633,10 @@ custom <thermo_style>` command, and per-atom quantities can be output
by the dump custom command.
If *c_ID* is used as a attribute, then the local vector calculated by
the compute is printed. If *c_ID[I]* is used, then I must be in the
range from 1-M, which will print the Ith column of the local array
with M columns calculated by the compute. See the discussion above
for how I can be specified with a wildcard asterisk to effectively
the compute is printed. If *c_ID[i]* is used, then :math:`i` must be in the
range from :math:`1-M`, which will print the Ith column of the local array
with :math:`M` columns calculated by the compute. See the discussion above
for how :math:`i` can be specified with a wildcard asterisk to effectively
specify multiple values.
The *f_ID* and *f_ID[I]* attributes allow local vectors or arrays
@ -649,11 +645,11 @@ should be replaced by the actual ID of the fix that has been defined
previously in the input script.
If *f_ID* is used as a attribute, then the local vector calculated by
the fix is printed. If *f_ID[I]* is used, then I must be in the
range from 1-M, which will print the Ith column of the local with M
columns calculated by the fix. See the discussion above for how I can
be specified with a wildcard asterisk to effectively specify multiple
values.
the fix is printed. If *f_ID[i]* is used, then :math:`i` must be in the
range :math:`1`--:math:`M`, which will print the :math:`i`\ th column of the
local with :math:`M` columns calculated by the fix. See the discussion above
for how :math:`i` can be specified with a wildcard asterisk to effectively
specify multiple values.
Here is an example of how to dump bond info for a system, including
the distance and energy of each bond:
@ -674,46 +670,47 @@ The *id*, *mol*, *proc*, *procp1*, *type*, *element*, *mass*, *vx*,
*Id* is the atom ID. *Mol* is the molecule ID, included in the data
file for molecular systems. *Proc* is the ID of the processor (0 to
Nprocs-1) that currently owns the atom. *Procp1* is the proc ID+1,
which can be convenient in place of a *type* attribute (1 to Ntypes)
for coloring atoms in a visualization program. *Type* is the atom
type (1 to Ntypes). *Element* is typically the chemical name of an
element, which you must assign to each type via the :doc:`dump_modify
element <dump_modify>` command. More generally, it can be any string
you wish to associated with an atom type. *Mass* is the atom mass.
*Vx*, *vy*, *vz*, *fx*, *fy*, *fz*, and *q* are components of atom
velocity and force and atomic charge.
:math:`N_\text{procs}-1`) that currently owns the atom.
*Procp1* is the proc ID+1, which can be convenient in place of a *type*
attribute (1 to :math:`N_\text{types}`) for coloring atoms in a visualization
program. *Type* is the atom type (1 to :math:`N_\text{types}`). *Element* is
typically the chemical name of an element, which you must assign to each type
via the :doc:`dump_modify element <dump_modify>` command. More generally, it
can be any string you wish to associated with an atom type. *Mass* is the atom
mass. The quantities *vx*, *vy*, *vz*, *fx*, *fy*, *fz*, and *q* are components
of atom velocity and force and atomic charge.
There are several options for outputting atom coordinates. The *x*,
*y*, *z* attributes write atom coordinates "unscaled", in the
appropriate distance :doc:`units <units>` (Angstroms, sigma, etc). Use
*xs*, *ys*, *zs* if you want the coordinates "scaled" to the box size,
so that each value is 0.0 to 1.0. If the simulation box is triclinic
(tilted), then all atom coords will still be between 0.0 and 1.0.
I.e. actual unscaled (x,y,z) = xs\*A + ys\*B + zs\*C, where (A,B,C) are
the non-orthogonal vectors of the simulation box edges, as discussed
on the :doc:`Howto triclinic <Howto_triclinic>` page.
*y*, and *z* attributes write atom coordinates "unscaled," in the
appropriate distance :doc:`units <units>` (:math:`\mathrm{\mathring A}`,
:math:`\sigma`, etc.). Use *xs*, *ys*, *zs* if you want the coordinates
"scaled" to the box size, so that each value is 0.0 to 1.0. If the simulation
box is triclinic (tilted), then all atom coords will still be between 0.0 and
1.0. The actual unscaled :math:`(x,y,z)` coordinate is
:math:`x_s a + y_s b + z_s c`, where :math:`(a,b,c)` are the non-orthogonal
vectors of the simulation box edges, as discussed on the
:doc:`Howto triclinic <Howto_triclinic>` page.
Use *xu*, *yu*, *zu* if you want the coordinates "unwrapped" by the
Use *xu*, *yu*, and *zu* if you want the coordinates "unwrapped" by the
image flags for each atom. Unwrapped means that if the atom has
passed through a periodic boundary one or more times, the value is
printed for what the coordinate would be if it had not been wrapped
back into the periodic box. Note that using *xu*, *yu*, *zu* means
back into the periodic box. Note that using *xu*, *yu*, and *zu* means
that the coordinate values may be far outside the box bounds printed
with the snapshot. Using *xsu*, *ysu*, *zsu* is similar to using
*xu*, *yu*, *zu*, except that the unwrapped coordinates are scaled by
with the snapshot. Using *xsu*, *ysu*, and *zsu* is similar to using
*xu*, *yu*, and *zu*, except that the unwrapped coordinates are scaled by
the box size. Atoms that have passed through a periodic boundary will
have the corresponding coordinate increased or decreased by 1.0.
The image flags can be printed directly using the *ix*, *iy*, *iz*
The image flags can be printed directly using the *ix*, *iy*, and *iz*
attributes. For periodic dimensions, they specify which image of the
simulation box the atom is considered to be in. An image of 0 means
it is inside the box as defined. A value of 2 means add 2 box lengths
to get the true value. A value of -1 means subtract 1 box length to
to get the true value. A value of :math:`-1` means subtract 1 box length to
get the true value. LAMMPS updates these flags as atoms cross
periodic boundaries during the simulation.
The *mux*, *muy*, *muz* attributes are specific to dipolar systems
The *mux*, *muy*, and *muz* attributes are specific to dipolar systems
defined with an atom style of *dipole*\ . They give the orientation of
the atom's point dipole moment. The *mu* attribute gives the
magnitude of the atom's dipole moment.
@ -724,7 +721,7 @@ style of *sphere*\ .
The *omegax*, *omegay*, and *omegaz* attributes are specific to
finite-size spherical particles that have an angular velocity. Only
certain atom styles, such as *sphere* define this quantity.
certain atom styles, such as *sphere*, define this quantity.
The *angmomx*, *angmomy*, and *angmomz* attributes are specific to
finite-size aspherical particles that have an angular momentum. Only
@ -749,10 +746,10 @@ command. Instead, global quantities can be output by the
can be output by the dump local command.
If *c_ID* is used as a attribute, then the per-atom vector calculated
by the compute is printed. If *c_ID[I]* is used, then I must be in
the range from 1-M, which will print the Ith column of the per-atom
array with M columns calculated by the compute. See the discussion
above for how I can be specified with a wildcard asterisk to
by the compute is printed. If *c_ID[i]* is used, then :math:`i` must be in
the range from 1 to :math:`M`, which will print the :math:`i`\ th column of the
per-atom array with :math:`M` columns calculated by the compute. See the
discussion above for how :math:`i` can be specified with a wildcard asterisk to
effectively specify multiple values.
The *f_ID* and *f_ID[I]* attributes allow vector or array per-atom
@ -766,11 +763,11 @@ Since it can time-average per-atom quantities produced by any
be written to a dump file.
If *f_ID* is used as a attribute, then the per-atom vector calculated
by the fix is printed. If *f_ID[I]* is used, then I must be in the
range from 1-M, which will print the Ith column of the per-atom array
with M columns calculated by the fix. See the discussion above for
how I can be specified with a wildcard asterisk to effectively specify
multiple values.
by the fix is printed. If *f_ID[i]* is used, then :math:`i` must be in the
range from 1 to :math:`M`, which will print the :math:`i`\ th column of the
per-atom array with :math:`M` columns calculated by the fix. See the
discussion above for how :math:`i` can be specified with a wildcard asterisk to
effectively specify multiple values.
The *v_name* attribute allows per-atom vectors calculated by a
:doc:`variable <variable>` to be output. The name in the attribute
@ -780,8 +777,7 @@ can be referenced, since it is the only style that generates per-atom
values. Variables of style *atom* can reference individual atom
attributes, per-atom attributes, thermodynamic keywords, or invoke
other computes, fixes, or variables when they are evaluated, so this
is a very general means of creating quantities to output to a dump
file.
is a very general means of creating quantities to output to a dump file.
The *i_name*, *d_name*, *i2_name*, *d2_name* attributes refer to
per-atom integer and floating-point vectors or arrays that have been
@ -789,10 +785,10 @@ added via the :doc:`fix property/atom <fix_property_atom>` command.
When that command is used specific names are given to each attribute
which are the "name" portion of these keywords. For arrays *i2_name*
and *d2_name*, the column of the array must also be included following
the name in brackets: e.g. d2_xyz[I], i2_mySpin[I], where I is in the
range from 1-M, where M is the number of columns in the custom array.
See the discussion above for how I can be specified with a wildcard
asterisk to effectively specify multiple values.
the name in brackets (e.g., d2_xyz[i], i2_mySpin[i], where :math:`i` is in the
range from 1 to :math:`M`, where :math:`M` is the number of columns in the
custom array). See the discussion above for how :math:`i` can be specified with
a wildcard asterisk to effectively specify multiple values.
See the :doc:`Modify <Modify>` page for information on how to add
new compute and fix styles to LAMMPS to calculate per-atom quantities
@ -807,9 +803,9 @@ To write gzipped dump files, you must either compile LAMMPS with the
-DLAMMPS_GZIP option or use the styles from the COMPRESS package.
See the :doc:`Build settings <Build_settings>` page for details.
While a dump command is active (i.e. has not been stopped by using
the undump command), no commands may be used that will change the
timestep (e.g. :doc:`reset_timestep <reset_timestep>`). LAMMPS
While a dump command is active (i.e., has not been stopped by using
the :doc:`undump command <undump>`), no commands may be used that will change
the timestep (e.g., :doc:`reset_timestep <reset_timestep>`). LAMMPS
will terminate with an error otherwise.
The *atom/gz*, *cfg/gz*, *custom/gz*, and *xyz/gz* styles are part of
@ -822,7 +818,7 @@ are part of the MPIIO package. They are only enabled if LAMMPS was
built with that package. See the :doc:`Build package <Build_package>`
page for more info.
The *xtc*, *dcd* and *yaml* styles are part of the EXTRA-DUMP package.
The *xtc*, *dcd*, and *yaml* styles are part of the EXTRA-DUMP package.
They are only enabled if LAMMPS was built with that package. See the
:doc:`Build package <Build_package>` page for more info.
@ -832,7 +828,8 @@ Related commands
:doc:`dump atom/adios <dump_adios>`, :doc:`dump custom/adios <dump_adios>`,
:doc:`dump cfg/uef <dump_cfg_uef>`, :doc:`dump h5md <dump_h5md>`,
:doc:`dump image <dump_image>`, :doc:`dump molfile <dump_molfile>`,
:doc:`dump_modify <dump_modify>`, :doc:`undump <undump>`, :doc:`write_dump <write_dump>`
:doc:`dump_modify <dump_modify>`, :doc:`undump <undump>`,
:doc:`write_dump <write_dump>`
Default
"""""""

181
doc/src/dump_modify.rst
View File

@ -33,7 +33,7 @@ Syntax
*delay* arg = Dstep
Dstep = delay output until this timestep
*element* args = E1 E2 ... EN, where N = # of atom types
E1,...,EN = element name, e.g. C or Fe or Ga
E1,...,EN = element name (e.g., C or Fe or Ga)
*every* arg = N
N = dump every this many timesteps
N can be a variable (see below)
@ -53,7 +53,7 @@ Syntax
*no* to not write the header
*image* arg = *yes* or *no*
*label* arg = string
string = character string (e.g. BONDS) to use in header of dump local file
string = character string (e.g., BONDS) to use in header of dump local file
*maxfiles* arg = Fmax
Fmax = keep only the most recent *Fmax* snapshots (one snapshot per file)
*nfile* arg = Nf
@ -153,8 +153,8 @@ be used if the *append yes* keyword is also used. The *N* argument is
the index of which frame to append to. A negative value can be
specified for *N*, which means a frame counted from the end of the
file. The *at* keyword can only be used if the dump_modify command is
before the first command that causes dump snapshots to be output,
e.g. a :doc:`run <run>` or :doc:`minimize <minimize>` command. Once the
before the first command that causes dump snapshots to be output
(e.g., a :doc:`run <run>` or :doc:`minimize <minimize>` command). Once the
dump file has been opened, this keyword has no further effect.
----------
@ -185,7 +185,7 @@ during an equilibration phase.
----------
The *element* keyword applies only to the dump *cfg*, *xyz*, and
*image* styles. It associates element names (e.g. H, C, Fe) with
*image* styles. It associates element names (e.g., H, C, Fe) with
LAMMPS atom types. See the list of element names at the bottom of
this page.
@ -262,7 +262,7 @@ in file tmp.times:
When using a file-style variable with the *every* keyword, the
file of timesteps must list a first timestep that is beyond the
current timestep (e.g. it cannot be 0). And it must list one or more
current timestep (e.g., it cannot be 0). And it must list one or more
timesteps beyond the length of the run you perform. This is because
the dump command will generate an error if the next timestep it reads
from the file is not a value greater than the current timestep. Thus
@ -275,10 +275,10 @@ in file tmp.times:
The *every/time* keyword can be used with any dump style except the
*dcd* and *xtc* styles. It does two things. It specifies that the
interval between dump snapshots will be set in simulation time,
i.e. in time units of the :doc:`units <units>` command. This can be
useful when the timestep size varies during a simulation run, e.g. by
use of the :doc:`fix dt/reset <fix_dt_reset>` command. The default is
interval between dump snapshots will be set in simulation time
(i.e. in time units of the :doc:`units <units>` command). This can be
useful when the timestep size varies during a simulation run (e.g., by
use of the :doc:`fix dt/reset <fix_dt_reset>` command). The default is
to specify the interval in timesteps; see the *every* keyword. The
*every/time* command also sets the interval value.
@ -340,7 +340,7 @@ file tmp.times:
When using a file-style variable with the *every/time* keyword, the
file of timesteps must list a first time that is beyond the time
associated with the current timestep (e.g. it cannot be 0.0). And
associated with the current timestep (e.g., it cannot be 0.0). And
it must list one or more times beyond the length of the run you
perform. This is because the dump command will generate an error
if the next time it reads from the file is not a value greater than
@ -409,16 +409,16 @@ by the text-based dump styles: *atom*, *local*, *custom*, *cfg*, and
*xyz* styles, and their MPIIO variants. Only the *line* or *none*
options can be used with the *atom* and *xyz* styles.
All the specified format strings are C-style formats, e.g. as used by
All the specified format strings are C-style formats, such as used by
the C/C++ printf() command. The *line* keyword takes a single
argument which is the format string for an entire line of output for
each atom (do not include a trailing "\n"), with N fields, which you
must enclose in quotes if it is more than one field. The *int* and
each atom (do not include a trailing "\n"), with :math:`N` fields, which you
must enclose in quotes if there is more than one field. The *int* and
*float* keywords take a single format argument and are applied to all
integer or floating-point quantities output. The setting for *M
string* also takes a single format argument which is used for the Mth
value output in each line, e.g. the fifth column is output in high
precision for "format 5 %20.15g".
integer or floating-point quantities output. The setting for *M string*
also takes a single format argument which is used for the :math:`M`\ th
value output in each line (e.g., the fifth column is output in high
precision by "format 5 %20.15g").
.. note::
@ -442,7 +442,7 @@ settings, reverting all values to their default format.
corresponding 8-byte form if it is needed when outputting those
values. However, when specifying the *line* option or *format M
string* option for those values, you should specify a format string
appropriate for an 8-byte signed integer, e.g. one with "%ld", if
appropriate for an 8-byte signed integer (e.g., one with "%ld") if
LAMMPS was compiled with the -DLAMMPS_BIGBIG option for 8-byte IDs.
.. note::
@ -462,7 +462,7 @@ settings, reverting all values to their default format.
will output the two atom IDs for atoms in each bond as integers. If
the dump_modify command were omitted, they would appear as
floating-point values, assuming they were large integers (more than 6
floating-point values, assuming they were large integers (more than six
digits). The "index" keyword should use the "%d" format since it is
not generated by a compute or fix, and is stored internally as an
integer.
@ -482,43 +482,43 @@ information typically written to the header.
----------
The *image* keyword applies only to the dump *atom* style. If the
image value is *yes*, 3 flags are appended to each atom's coords which
image value is *yes*, three flags are appended to each atom's coords which
are the absolute box image of the atom in each dimension. For
example, an x image flag of -2 with a normalized coord of 0.5 means
the atom is in the center of the box, but has passed through the box
boundary 2 times and is really 2 box lengths to the left of its
example, an :math:`x` image flag of :math:`-2` with a normalized coord of 0.5
means the atom is in the center of the box, but has passed through the box
boundary twice and is really two box lengths to the left of its
current coordinate. Note that for dump style *custom* these various
values can be printed in the dump file by using the appropriate atom
attributes in the dump command itself.
----------
The *label* keyword applies only to the dump *local* style. When
it writes local information, such as bond or angle topology
to a dump file, it will use the specified *label* to format
the header. By default this includes 2 lines:
The *label* keyword applies only to the dump *local* style.
When it writes local information, such as bond or angle topology
to a dump file, it will use the specified *label* to format the header.
By default this includes two lines:
.. parsed-literal::
ITEM: NUMBER OF ENTRIES
ITEM: ENTRIES ...
The word "ENTRIES" will be replaced with the string specified,
e.g. BONDS or ANGLES.
The word "ENTRIES" will be replaced with the string specified
(e.g., BONDS or ANGLES).
----------
The *maxfiles* keyword can only be used when a '\*' wildcard is
included in the dump file name, i.e. when writing a new file(s) for
each snapshot. The specified *Fmax* is how many snapshots will be
included in the dump file name (i.e., when writing a new file(s) for
each snapshot). The specified *Fmax* is how many snapshots will be
kept. Once this number is reached, the file(s) containing the oldest
snapshot is deleted before a new dump file is written. If the
specified *Fmax* <= 0, then all files are retained.
specified :math:`\text{Fmax} \le 0`, then all files are retained.
This can be useful for debugging, especially if you don't know on what
timestep something bad will happen, e.g. when LAMMPS will exit with an
error. You can dump every timestep, and limit the number of dump
files produced, even if you run for 1000s of steps.
This can be useful for debugging, especially if you do not know on what
timestep something bad will happen (e.g., when LAMMPS will exit with an
error). You can dump every time step and limit the number of dump
files produced, even if you run for thousands of steps.
----------
@ -527,28 +527,29 @@ The *nfile* or *fileper* keywords can be used in conjunction with the
styles except the *dcd*, *image*, *movie*, *xtc*, and *xyz* styles
(for which "%" is not allowed). As explained on the :doc:`dump <dump>`
command doc page, the "%" character causes the dump file to be written
in pieces, one piece for each of P processors. By default P = the
number of processors the simulation is running on. The *nfile* or
*fileper* keyword can be used to set P to a smaller value, which can
in pieces, one piece for each of :math:`P` processors. By default, :math:`P`
is the number of processors the simulation is running on. The *nfile* or
*fileper* keyword can be used to set :math:`P` to a smaller value, which can
be more efficient when running on a large number of processors.
The *nfile* keyword sets P to the specified Nf value. For example, if
Nf = 4, and the simulation is running on 100 processors, 4 files will
be written, by processors 0,25,50,75. Each will collect information
from itself and the next 24 processors and write it to a dump file.
The *nfile* keyword sets :math:`P` to the specified :math:`N_f` value.
For example, if :math:`N_f = 4`, and the simulation is running on 100
processors, four files will be written by processors 0, 25, 50, and 75.
Each will collect information from itself and the next 24 processors and write
it to a dump file.
For the *fileper* keyword, the specified value of Np means write one
file for every Np processors. For example, if Np = 4, every fourth
processor (0,4,8,12,etc) will collect information from itself and the
next 3 processors and write it to a dump file.
For the *fileper* keyword, the specified value of :math:`N_p` means write one
file for every :math:`N_p` processors. For example, if :math:`N_p = 4`,
every fourth processor (0, 4, 8, 12, etc.) will collect information from itself
and the next three processors and write it to a dump file.
----------
The *pad* keyword only applies when the dump filename is specified
with a wildcard "\*" character which becomes the timestep. If *pad* is
0, which is the default, the timestep is converted into a string of
unpadded length, e.g. 100 or 12000 or 2000000. When *pad* is
specified with *Nchar* > 0, the string is padded with leading zeroes
unpadded length (e.g., 100 or 12000 or 2000000). When *pad* is
specified with *Nchar* :math:`>` 0, the string is padded with leading zeroes
so they are all the same length = *Nchar*\ . For example, pad 7 would
yield 0000100, 0012000, 2000000. This can be useful so that
post-processing programs can easily read the files in ascending
@ -570,9 +571,9 @@ because it requires no extra computation.
----------
The *precision* keyword only applies to the dump *xtc* style. A
specified value of N means that coordinates are stored to 1/N
nanometer accuracy, e.g. for N = 1000, the coordinates are written to
1/1000 nanometer accuracy.
specified value of :math:`N` means that coordinates are stored to :math:`1/N`
nanometer accuracy (e.g., for :math:`N = 1000`, the coordinates are written to
:math:`1/1000` nanometer accuracy).
----------
@ -582,7 +583,7 @@ be written, by refreshing a compute that is used as a threshold for
determining which atoms are included in a dump snapshot. The
specified *c_ID* gives the ID of the compute. It is prefixed by "c\_"
to indicate a compute, which is the only current option. At some
point, other options may be added, e.g. fixes or variables.
point, other options may be added (e.g., fixes or variables).
.. note::
@ -615,19 +616,19 @@ commands:
The :doc:`compute displace/atom <compute_displace_atom>` command
calculates the displacement of each atom from its reference position.
The "4" index is the scalar displacement; 1,2,3 are the xyz components
of the displacement. The :doc:`dump_modify thresh <dump_modify>`
command will cause only atoms that have displaced more than 0.6
Angstroms to be output on a given snapshot (assuming metal units).
However, note that when an atom is output, we also need to update the
reference position for that atom to its new coordinates. So that it
will not be output in every snapshot thereafter. That reference
position is stored by :doc:`compute displace/atom <compute_displace_atom>`. So the dump_modify
*refresh* option triggers a call to compute displace/atom at the end
of every dump to perform that update. The *refresh check* option
shown as part of the :doc:`compute displace/atom <compute_displace_atom>` command enables the compute
to respond to the call from the dump command, and update the
appropriate reference positions. This is done be defining an
The "4" index is the scalar displacement; 1, 2, and 3 are the :math:`xyz`
components of the displacement. The :doc:`dump_modify thresh <dump_modify>`
command will cause only atoms that have displaced more than
:math:`0.6~\mathrm{\mathring A}` to be output on a given snapshot (assuming
metal units). However, note that when an atom is output, we also need to
update the reference position for that atom to its new coordinates. So that it
will not be output in every snapshot thereafter. That reference position is
stored by :doc:`compute displace/atom <compute_displace_atom>`. So the
dump_modify *refresh* option triggers a call to compute displace/atom at the
end of every dump to perform that update. The *refresh check* option
shown as part of the :doc:`compute displace/atom <compute_displace_atom>`
command enables the compute to respond to the call from the dump command, and
update the appropriate reference positions. This is done be defining an
:doc:`atom-style variable <variable>`, *check* in this example, which
calculates a Boolean value (0 or 1) for each atom, based on the same
criterion used by dump_modify thresh.
@ -661,18 +662,18 @@ value of *yes* means atom coords are written in normalized units from
0.0 to 1.0 in each box dimension. If the simulation box is triclinic
(tilted), then all atom coords will still be between 0.0 and 1.0. A
value of *no* means they are written in absolute distance units
(e.g. Angstroms or sigma).
(e.g., :math:`\mathrm{\mathring A}` or :math:`\sigma`).
----------
The *sfactor* and *tfactor* keywords only apply to the dump *xtc*
style. They allow customization of the unit conversion factors used
when writing to XTC files. By default they are initialized for
when writing to XTC files. By default, they are initialized for
whatever :doc:`units <units>` style is being used, to write out
coordinates in nanometers and time in picoseconds. I.e. for *real*
coordinates in nanometers and time in picoseconds. For example, for *real*
units, LAMMPS defines *sfactor* = 0.1 and *tfactor* = 0.001, since the
Angstroms and fs used by *real* units are 0.1 nm and 0.001 ps
respectively. If you are using a units system with distance and time
:math:`\mathrm{\mathring A}}` and fs used by *real* units are 0.1 nm and
0.001 ps, respectively. If you are using a units system with distance and time
units far from nm and ps, you may wish to write XTC files with
different units, since the compression algorithm used in XTC files is
most effective when the typical magnitude of position data is between
@ -683,18 +684,19 @@ most effective when the typical magnitude of position data is between
The *sort* keyword determines whether lines of per-atom output in a
snapshot are sorted or not. A sort value of *off* means they will
typically be written in indeterminate order, either in serial or
parallel. This is the case even in serial if the :doc:`atom_modify sort <atom_modify>` option is turned on, which it is by default, to
improve performance. A sort value of *id* means sort the output by
atom ID. A sort value of N or -N means sort the output by the value
in the Nth column of per-atom info in either ascending or descending
order.
parallel. This is the case even in serial if the
:doc:`atom_modify sort <atom_modify>` option is turned on, which it is by
default, to improve performance. A sort value of *id* means sort the output by
atom ID. A sort value of :math:`N` or :math:`-N` means sort the output by the
value in the :math:`N`\ th column of per-atom info in either ascending or
descending order.
The dump *local* style cannot be sorted by atom ID, since there are
typically multiple lines of output per atom. Some dump styles, such
as *dcd* and *xtc*, require sorting by atom ID to format the output
file correctly. If multiple processors are writing the dump file, via
the "%" wildcard in the dump filename and the *nfile* or *fileper*
keywords are set to non-default values (i.e. the number of dump file
keywords are set to non-default values (i.e., the number of dump file
pieces is not equal to the number of procs), then sorting cannot be
performed.
@ -729,11 +731,12 @@ are written to the dump file or included in the image. The possible
attributes that can be tested for are the same as those that can be
specified in the :doc:`dump custom <dump>` command, with the exception
of the *element* attribute, since it is not a numeric value. Note
that a different attributes can be used than those output by the :doc:`dump custom <dump>` command. E.g. you can output the coordinates and
stress of atoms whose energy is above some threshold.
that a different attributes can be used than those output by the
:doc:`dump custom <dump>` command. For example, you can output the coordinates
and stress of atoms whose energy is above some threshold.
If an atom-style variable is used as the attribute, then it can
produce continuous numeric values or effective Boolean 0/1 values
produce continuous numeric values or effective Boolean 0/1 values,
which may be useful for the comparison operator. Boolean values can
be generated by variable formulas that use comparison or Boolean math
operators or special functions like gmask() and rmask() and grmask().
@ -749,7 +752,7 @@ Three examples follow.
dump_modify ... thresh ix != LAST
This will dump atoms which have crossed the periodic x boundary of the
This will dump atoms which have crossed the periodic :math:`x` boundary of the
simulation box since the last dump. (Note that atoms that crossed
once and then crossed back between the two dump timesteps would not be
included.)
@ -769,9 +772,8 @@ 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 1/2 to greater than 1/2 (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 "\|\^".
@ -783,7 +785,7 @@ threshold criterion is met. Otherwise it is not met.
The *time* keyword only applies to the dump *atom*, *custom*, *local*,
and *xyz* styles (and their COMPRESS package versions *atom/gz*,
*custom/gz* and *local/gz*\ ). For the first 3 styles, if set to
*custom/gz* and *local/gz*\ ). For the first three styles, if set to
*yes*, each frame will will contain two extra lines before the "ITEM:
TIMESTEP" entry:
@ -798,7 +800,7 @@ as the timestep value.
This will output the current elapsed simulation time in current
time units equivalent to the :doc:`thermo keyword <thermo_style>` *time*\ .
This is to simplify post-processing of trajectories using a variable time
step, e.g. when using :doc:`fix dt/reset <fix_dt_reset>`.
step (e.g., when using :doc:`fix dt/reset <fix_dt_reset>`).
The default setting is *no*\ .
----------
@ -836,9 +838,8 @@ compression level can be controlled by the :code:`compression_level`
keyword. File names with these styles have to end in either
:code:`.gz` or :code:`.zst`.
GZ supports compression levels from -1 (default), 0 (no compression),
and 1 to
9. 9 being the best compression. The COMPRESS :code:`/gz` styles use 9
GZ supports compression levels from :math:`-1` (default), 0 (no compression),
and 1 to 9, 9 being the best compression. The COMPRESS :code:`/gz` styles use 9
as default compression level.
Zstd offers a wider range of compression levels, including negative