jianmu
/
lammps
forked from lijiext/lammps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

new reset_ids command and dump_modify delay option

This commit is contained in:
Steven J. Plimpton 2018-03-28 11:31:35 -06:00
parent b5b0f67bcd
commit 5fd17670b1
14 changed files with 4011 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1266
doc/Section_commands.txt Normal file
View File

File diff suppressed because it is too large Load Diff

137
doc/compute_displace_atom.txt Normal file
View File

@ -0,0 +1,137 @@
"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)
:line
compute displace/atom command :h3
[Syntax:]
compute ID group-ID displace/atom :pre
ID, group-ID are documented in "compute"_compute.html command :ulb,l
displace/atom = style name of this compute command :l
zero or more keyword/arg pairs may be appended :l
keyword = {refresh} :l
{replace} arg = per-atom variable ID :pre
:ule
[Examples:]
compute 1 all displace/atom
compute 1 all displace/atom refresh myVar :pre
[Description:]
Define a computation that calculates the current displacement of each
atom in the group from its original (reference) coordinates, including
all effects due to atoms passing thru periodic boundaries.
A vector of four quantities per atom is calculated by this compute.
The first 3 elements of the vector are the dx,dy,dz displacements.
The 4th component is the total displacement, i.e. sqrt(dx*dx + dy*dy +
dz*dz).
The displacement of an atom is from its original position at the time
the compute command was issued. The value of the displacement will be
0.0 for atoms not in the specified compute group.
NOTE: Initial coordinates are stored in "unwrapped" form, by using the
image flags associated with each atom. See the "dump
custom"_dump.html command for a discussion of "unwrapped" coordinates.
See the Atoms section of the "read_data"_read_data.html command for a
discussion of image flags and how they are set for each atom. You can
reset the image flags (e.g. to 0) before invoking this compute by
using the "set image"_set.html command.
NOTE: If you want the quantities calculated by this compute to be
continuous when running from a "restart file"_read_restart.html, then
you should use the same ID for this compute, as in the original run.
This is so that the fix this compute creates to store per-atom
quantities will also have the same ID, and thus be initialized
correctly with time=0 atom coordinates from the restart file.
:line
The {refresh} option can be used in conjuction with the "dump_modify
refresh" command to generate incremental dump files.
The definition and motivation of an incremental dump file is as
follows. Instead of outputting all atoms at each snapshot (with some
associated values), you may only wish to output the subset of atoms
with a value that has changed in some way compared to the value the
last time that atom was output. In some scenarios this can result in
a dramatically smaller dump file. If desired, by post-processing the
sequence of snapshots, the values for all atoms at all timesteps can
be inferred.
A concrete example using this compute, is a simulation of atom
diffusion in a solid, represented as atoms on a lattice. Diffusive
hops are rare. Imagine that when a hop occurs an atom moves more than
a distance {Dhop}. For any snapshot we only want to output atoms that
have hopped since the last snapshot. This can be accomplished with
something like the following commands:
write_dump all custom tmp.dump id type x y z # see comment below :pre
variable Dhop equal 0.6
variable check atom "c_dsp[4] > v_Dhop"
compute dsp all displace/atom refresh check
dump 1 all custom 100 tmp.dump id type x y z
dump_modify 1 append yes thresh c_dsp[4] > ${Dhop} &
refresh c_dsp delay 100 :pre
The "dump_modify thresh"_dump_modify.html command will only ouptut
atoms that have displaced more than 0.6 Angstroms on each snapshot
(assuming metal units). The dump_modify {refresh} option triggers a
call to this compute at the end of every dump.
The {refresh} argument for this compute is the ID of an "atom-style
variable"_variable.html which calculates a Boolean value (0 or 1)
based on the same criterion used by dump_modify thresh. This compute
evaluates the atom-style variable. For each atom that returns 1
(true), the original (reference) coordinates of the atom (stored by
this compute) are updated.
The effect of these commands is that a particular atom will only be
output in the dump file on the snapshot after it makes a diffusive
hop. It will not be output again until it makes another hop.
Note that in the first snapshot of a subsequent run, no atoms will be
typically be output. That is because the initial displacement for all
atoms is 0.0. If an initial dump snapshot is desired, containing the
initial reference positions of all atoms, one way to do this is
illustrated above. An initial write_dump command can be used before
the first run. It will contain the positions of all the atoms,
Options in the "dump_modify"_dump_modify.html command above will
append new output to that same file and delay the output until a later
timestep. The {delay} setting avoids a second time = 0 snapshot which
would be empty.
:line
[Output info:]
This compute calculates a per-atom array with 4 columns, which can be
accessed by indices 1-4 by any command that uses per-atom values from
a compute as input. See "Section
6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output
options.
The per-atom array values will be in distance "units"_units.html.
This compute supports the {refresh} option as explained above, for use
in conjunction with "dump_modify refresh"_dump_modify.html to generate
incremental dump files.
[Restrictions:] none
[Related commands:]
"compute msd"_compute_msd.html, "dump custom"_dump.html, "fix
store/state"_fix_store_state.html
[Default:] none

335
doc/create_atoms.txt Normal file
View File

@ -0,0 +1,335 @@
"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)
:line
create_atoms command :h3
[Syntax:]
create_atoms type style args keyword values ... :pre
type = atom type (1-Ntypes) of atoms to create (offset for molecule creation) :ulb,l
style = {box} or {region} or {single} or {random} :l
{box} args = none
{region} args = region-ID
region-ID = particles will only be created if contained in the region
{single} args = x y z
x,y,z = coordinates of a single particle (distance units)
{random} args = N seed region-ID
N = number of particles to create
seed = random # seed (positive integer)
region-ID = create atoms within this region, use NULL for entire simulation box :pre
zero or more keyword/value pairs may be appended :l
keyword = {mol} or {basis} or {remap} or {var} or {set} or {units} :l
{mol} value = template-ID seed
template-ID = ID of molecule template specified in a separate "molecule"_molecule.html command
seed = random # seed (positive integer)
{basis} values = M itype
M = which basis atom
itype = atom type (1-N) to assign to this basis atom
{remap} value = {yes} or {no}
{var} value = name = variable name to evaluate for test of atom creation
{set} values = dim name
dim = {x} or {y} or {z}
name = name of variable to set with x, y, or z atom position
{rotate} values = theta Rx Ry Rz
theta = rotation angle for single molecule (degrees)
Rx,Ry,Rz = rotation vector for single molecule
{units} value = {lattice} or {box}
{lattice} = the geometry is defined in lattice units
{box} = the geometry is defined in simulation box units :pre
:ule
[Examples:]
create_atoms 1 box
create_atoms 3 region regsphere basis 2 3
create_atoms 3 single 0 0 5
create_atoms 1 box var v set x xpos set y ypos :pre
[Description:]
This command creates atoms (or molecules) on a lattice, or a single
atom (or molecule), or a random collection of atoms (or molecules), as
an alternative to reading in their coordinates explicitly via a
"read_data"_read_data.html or "read_restart"_read_restart.html
command. A simulation box must already exist, which is typically
created via the "create_box"_create_box.html command. Before using
this command, a lattice must also be defined using the
"lattice"_lattice.html 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".
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 "molecule"_molecule.html 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.
For the {box} style, the create_atoms command fills the entire
simulation box with particles on the lattice. If your simulation box
is periodic, you should insure its size is a multiple of the lattice
spacings, to avoid unwanted atom overlaps at the box boundaries. If
your box is periodic and a multiple of the lattice spacing in a
particular dimension, LAMMPS is careful to put exactly one particle at
the boundary (on either side of the box), not zero or two.
For the {region} style, a geometric volume is filled with particles on
the lattice. This volume what is inside the simulation box and is
also consistent with the region volume. See the "region"_region.html
command for details. Note that a region can be specified so that its
"volume" is either inside or outside a geometric boundary. Also note
that if your region is the same size as a periodic simulation box (in
some dimension), LAMMPS does not implement the same logic described
above as for the {box} style, to insure exactly one particle at
periodic boundaries. if this is what you desire, you should either
use the {box} style, or tweak the region size to get precisely the
particles you want.
For the {single} style, a single particle is added to the system at
the specified coordinates. This can be useful for debugging purposes
or to create a tiny system with a handful of particles at specified
positions.
For the {random} style, N particles are added to the system at
randomly generated coordinates, which can be useful for generating an
amorphous system. The particles are created one by one using the
specified random number {seed}, resulting in the same set of particles
coordinates, independent of how many processors are being used in the
simulation. If the {region-ID} argument is specified as NULL, then
the created particles will be anywhere in the simulation box. If a
{region-ID} is specified, a geometric volume is filled which is both
inside the simulation box and is also consistent with the region
volume. See the "region"_region.html command for details. Note that
a region can be specified so that its "volume" is either inside or
outside a geometric boundary.
NOTE: Particles generated by the {random} style will typically be
highly overlapped which will cause many interatomic potentials to
compute large energies and forces. Thus you should either perform an
"energy minimization"_minimize.html or run dynamics with "fix
nve/limit"_fix_nve_limit.html to equilibrate such a system, before
running normal dynamics.
Note that this command adds particles to those that already exist.
This means it can be used to add particles to a system previously read
in from a data or restart file. Or the create_atoms command can be
used multiple times, to add multiple sets of particles to the
simulation. For example, grain boundaries can be created, by
interleaving create_atoms with "lattice"_lattice.html commands
specifying different orientations. By using the create_atoms command
in conjunction with the "delete_atoms"_delete_atoms.html command,
reasonably complex geometries can be created, or a protein can be
solvated with a surrounding box of water molecules.
In all these cases, care should be taken to insure that new atoms do
not overlap existing atoms inappropriately, especially if molecules
are being added. The "delete_atoms"_delete_atoms.html command can be
used to remove overlapping atoms or molecules.
NOTE: You cannot use any of the styles explained above to create atoms
that are outside the simulation box; they will just be ignored by
LAMMPS. This is true even if you are using shrink-wrapped box
boundaries, as specified by the "boundary"_boundary.html command.
However, you can first use the "change_box"_change_box.html command to
temporarily expand the box, then add atoms via create_atoms, then
finally use change_box command again if needed to re-shrink-wrap the
new atoms. See the "change_box"_change_box.html doc page for an
example of how to do this, using the create_atoms {single} style to
insert a new atom outside the current simulation box.
:line
Individual atoms are inserted by this command, unless the {mol}
keyword is used. It specifies a {template-ID} previously defined
using the "molecule"_molecule.html command, which reads a file that
defines the molecule. The coordinates, atom types, charges, etc, as
well as any bond/angle/etc and special neighbor information for the
molecule can be specified in the molecule file. See the
"molecule"_molecule.html command for details. The only settings
required to be in this file are the coordinates and types of atoms in
the molecule.
Using a lattice to add molecules, e.g. via the {box} or {region} or
{single} styles, is exactly the same as adding atoms on lattice
points, except that entire molecules are added at each point, i.e. on
the point defined by each basis atom in the unit cell as it tiles the
simulation box or region. This is done by placing the geometric
center of the molecule at the lattice point, and giving the molecule a
random orientation about the point. The random {seed} specified with
the {mol} keyword is used for this operation, and the random numbers
generated by each processor are different. This means the coordinates
of individual atoms (in the molecules) will be different when running
on different numbers of processors, unlike when atoms are being
created in parallel.
Also note that because of the random rotations, it may be important to
use a lattice with a large enough spacing that adjacent molecules will
not overlap, regardless of their relative orientations.
NOTE: If the "create_box"_create_box.html command is used to create
the simulation box, followed by the create_atoms command with its
{mol} option for adding molecules, then you typically need to use the
optional keywords allowed by the "create_box"_create_box.html command
for extra bonds (angles,etc) or extra special neighbors. This is
because by default, the "create_box"_create_box.html command sets up a
non-molecular system which doesn't allow molecules to be added.
:line
This is the meaning of the other allowed keywords.
The {basis} keyword is only used when atoms (not molecules) are being
created. It specifies an atom type that will be assigned to specific
basis atoms as they are created. See the "lattice"_lattice.html
command for specifics on how basis atoms are defined for the unit cell
of the lattice. By default, all created atoms are assigned the
argument {type} as their atom type.
The {remap} keyword only applies to the {single} style. If it is set
to {yes}, then if the specified position is outside the simulation
box, it will mapped back into the box, assuming the relevant
dimensions are periodic. If it is set to {no}, no remapping is done
and no particle is created if its position is outside the box.
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. The {name} specified for the {var}
keyword is the name of an "equal-style variable"_variable.html 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 coordinate). If used, these other variables must be
"internal-style variables"_variable.html 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.
When an atom is created, its 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.
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" "thermo_style"_thermo_style.html keywords which
converts lattice spacings to distance. Click on the image for a
larger version.
dimension 2
variable x equal 100
variable y equal 25
lattice hex 0.8442
region box block 0 $x 0 $y -0.5 0.5
create_box 1 box :pre
variable xx internal 0.0
variable yy internal 0.0
variable v equal "(0.2*v_y*ylat * cos(v_xx/xlat * 2.0*PI*4.0/v_x) + 0.5*v_y*ylat - v_yy) > 0.0"
create_atoms 1 box var v set x xx set y yy
write_dump all atom sinusoid.lammpstrj :pre
:c,image(JPG/sinusoid_small.jpg,JPG/sinusoid.jpg)
The {rotate} keyword can only be used with the {single} style and
when adding a single molecule. It allows to specify the orientation
at which the molecule is inserted. The axis of rotation is
determined by the rotation vector (Rx,Ry,Rz) 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
rule: if your right-hand's thumb points along {R}, then your fingers
wrap around the axis in the direction of rotation.
The {units} keyword determines the meaning of the distance units used
to specify the coordinates of the one particle created by the {single}
style. A {box} value selects standard distance units as defined by
the "units"_units.html command, e.g. Angstroms for units = real or
metal. A {lattice} value means the distance units are in lattice
spacings.
:line
Atom IDs are assigned to created atoms in the following way. The
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.
Aside from their ID, atom type, and xyz position, other properties of
created atoms are set to default values, depending on which quantities
are defined by the chosen "atom style"_atom_style.html. See the "atom
style"_atom_style.html command for more details. See the
"set"_set.html and "velocity"_velocity.html commands for info on how
to change these values.
charge = 0.0
dipole moment magnitude = 0.0
diameter = 1.0
shape = 0.0 0.0 0.0
density = 1.0
volume = 1.0
velocity = 0.0 0.0 0.0
angular velocity = 0.0 0.0 0.0
angular momentum = 0.0 0.0 0.0
quaternion = (1,0,0,0)
bonds, angles, dihedrals, impropers = none :ul
If molecules are being created, these defaults can be overridden by
values specified in the file read by the "molecule"_molecule.html
command. E.g. 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.
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
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
and thus also set the mass for the particle to 1.0.
The "set"_set.html command can be used to override many of these
default settings.
:line
[Restrictions:]
An "atom_style"_atom_style.html must be previously defined to use this
command.
A rotation vector specified for a single molecule must be in
the z-direction for a 2d model.
[Related commands:]
"lattice"_lattice.html, "region"_region.html, "create_box"_create_box.html,
"read_data"_read_data.html, "read_restart"_read_restart.html
[Default:]
The default for the {basis} keyword is that all created atoms are
assigned the argument {type} as their atom type (when single atoms are
being created). The other defaults are {remap} = no, {rotate} =
random, and {units} = lattice.

152
doc/delete_atoms.txt Normal file
View File

@ -0,0 +1,152 @@
"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)
:line
delete_atoms command :h3
[Syntax:]
delete_atoms style args keyword value ... :pre
style = {group} or {region} or {overlap} or {porosity} :ulb,l
{group} args = group-ID
{region} args = region-ID
{overlap} args = cutoff group1-ID group2-ID
cutoff = delete one atom from pairs of atoms within the cutoff (distance units)
group1-ID = one atom in pair must be in this group
group2-ID = other atom in pair must be in this group
{porosity} args = region-ID fraction seed
region-ID = region within which to perform deletions
fraction = delete this fraction of atoms
seed = random number seed (positive integer) :pre
zero or more keyword/value pairs may be appended :l
keyword = {compress} or {bond} or {mol} :l
{compress} value = {no} or {yes}
{bond} value = {no} or {yes}
{mol} value = {no} or {yes} :pre
:ule
[Examples:]
delete_atoms group edge
delete_atoms region sphere compress no
delete_atoms overlap 0.3 all all
delete_atoms overlap 0.5 solvent colloid
delete_atoms porosity cube 0.1 482793 bond yes :pre
[Description:]
Delete the specified atoms. This command can be used 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).
For style {group}, all atoms belonging to the group are deleted.
For style {region}, all atoms in the region volume are deleted.
Additional atoms can be deleted if they are in a molecule for which
one or more atoms were deleted within the region; see the {mol}
keyword discussion below.
For style {overlap} pairs of atoms whose distance of separation is
within the specified cutoff distance are searched for, and one of the
2 atoms is deleted. Only pairs where one of the two atoms is in the
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
{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
is that at the end of the deletion operation, enough deletions will
have occurred that no atom pairs within the cutoff will remain
(subject to the group restriction). There is no guarantee that the
minimum number of atoms will be deleted, or that the same atoms will
be deleted when running on different numbers of processors.
For style {porosity} a specified {fraction} of atoms are deleted
within the specified region. For example, if fraction is 0.1, then
10% of the atoms will be deleted. The atoms to delete are chosen
randomly. There is no guarantee that the exact fraction of atoms will
be deleted, or that the same atoms will be deleted when running on
different numbers of processors.
If the {compress} keyword is set to {yes}, then after atoms are
deleted, then atom IDs are re-assigned so that they run from 1 to the
number of atoms in the system. Note that this is not done for
molecular systems (see the "atom_style"_atom_style.html command),
regardless of the {compress} setting, since it would foul up the bond
connectivity that has already been assigned. However, the
"reset_ids"_reset_ids.html command can be used after this command to
accomplish the same thing.
Note that the re-assignement of IDs is not really a compression, where
gaps in atom IDs are removed by decrementing atom IDs that are larger.
Instead the IDs for all atoms are erased, and new IDs are assigned so
that the atoms owned by individual processors have consecutive IDs, as
the "create_atoms"_create_atoms.html command explains.
A molecular system with fixed bonds, angles, dihedrals, or improper
interactions, is one where the topology of the interactions is
typically defined in the data file read by the
"read_data"_read_data.html command, and where the interactions
themselves are defined with the "bond_style"_bond_style.html,
"angle_style"_angle_style.html, 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 interaction is computed. The {bond} and {mol}
keywords offer two ways to do that.
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
the remaining atoms.
It the {mol} keyword is set to {yes}, then for every atom that is
deleted, all other atoms in the same molecule (with the same molecule
ID) will also be deleted. This is not done for atoms with molecule ID
= 0, since such an ID is assumed to flag isolated atoms that are not
part of molecules.
NOTE: The molecule deletion operation in invoked after all individual
atoms have been deleted using the rules described above for each
style. This means additional atoms may be deleted that are not in the
group or region, that are not required by the overlap cutoff
criterion, or that will create a higher fraction of porosity than was
requested.
[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
find overlapping atom pairs, it also means that you must define a
"pair style"_pair_style.html with the minimum force cutoff distance
between any pair of atoms types (plus the "neighbor"_neighbor.html
skin) >= the specified overlap cutoff.
If the "special_bonds"_special_bonds.html command is used with a
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.
The {bond yes} option cannot be used with molecular systems defined
using molecule template files via the "molecule"_molecule.html and
"atom_style template"_atom_style.html commands.
[Related commands:]
"create_atoms"_create_atoms.html, "reset_ids"_reset_ids.html
[Default:]
The option defaults are compress = yes, bond = no, mol = no.

664
doc/dump.txt Normal file
View File

@ -0,0 +1,664 @@
"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)
:line
dump command :h3
"dump vtk"_dump_vtk.html command :h3
"dump h5md"_dump_h5md.html command :h3
"dump molfile"_dump_molfile.html command :h3
"dump netcdf"_dump_netcdf.html command :h3
"dump image"_dump_image.html command :h3
"dump movie"_dump_image.html command :h3
[Syntax:]
dump ID group-ID style N file args :pre
ID = user-assigned name for the dump :ulb,l
group-ID = ID of the group of atoms to be dumped :l
style = {atom} or {atom/gz} or {atom/mpiio} or {cfg} or {cfg/gz} or {cfg/mpiio} or {custom} or {custom/gz} or {custom/mpiio} or {dcd} or {h5md} or {image} or or {local} or {molfile} or {movie} or {netcdf} or {netcdf/mpiio} or {vtk} or {xtc} or {xyz} or {xyz/gz} or {xyz/mpiio} :l
N = dump every this many timesteps :l
file = name of file to write dump info to :l
args = list of arguments for a particular style :l
{atom} args = none
{atom/gz} args = none
{atom/mpiio} args = none
{cfg} args = same as {custom} args, see below
{cfg/gz} args = same as {custom} args, see below
{cfg/mpiio} args = same as {custom} args, see below
{custom}, {custom/gz}, {custom/mpiio} args = see below
{dcd} args = none
{h5md} args = discussed on "dump h5md"_dump_h5md.html doc page
{image} args = discussed on "dump image"_dump_image.html doc page
{local} args = see below
{molfile} args = discussed on "dump molfile"_dump_molfile.html doc page
{movie} args = discussed on "dump image"_dump_image.html doc page
{netcdf} args = discussed on "dump netcdf"_dump_netcdf.html doc page
{netcdf/mpiio} args = discussed on "dump netcdf"_dump_netcdf.html doc page
{vtk} args = same as {custom} args, see below, also "dump vtk"_dump_vtk.html doc page
{xtc} args = none
{xyz} args = none
{xyz/gz} args = none
{xyz/mpiio} args = none :pre
{custom} or {custom/gz} or {custom/mpiio} or {netcdf} or {netcdf/mpiio} args = list of atom attributes :l
possible attributes = id, mol, proc, procp1, type, element, mass,
x, y, z, xs, ys, zs, xu, yu, zu,
xsu, ysu, zsu, ix, iy, iz,
vx, vy, vz, fx, fy, fz,
q, mux, muy, muz, mu,
radius, diameter, omegax, omegay, omegaz,
angmomx, angmomy, angmomz, tqx, tqy, tqz,
c_ID, c_ID\[N\], f_ID, f_ID\[N\], v_name :pre
id = atom ID
mol = molecule ID
proc = ID of processor that owns atom
procp1 = ID+1 of processor that owns atom
type = atom type
element = name of atom element, as defined by "dump_modify"_dump_modify.html command
mass = atom mass
x,y,z = unscaled atom coordinates
xs,ys,zs = scaled atom coordinates
xu,yu,zu = unwrapped atom coordinates
xsu,ysu,zsu = scaled unwrapped atom coordinates
ix,iy,iz = box image that the atom is in
vx,vy,vz = atom velocities
fx,fy,fz = forces on atoms
q = atom charge
mux,muy,muz = orientation of dipole moment of atom
mu = magnitude of dipole moment of atom
radius,diameter = radius,diameter of spherical particle
omegax,omegay,omegaz = angular velocity of spherical particle
angmomx,angmomy,angmomz = angular momentum of aspherical particle
tqx,tqy,tqz = torque on finite-size particles
c_ID = per-atom vector calculated by a compute with ID
c_ID\[I\] = Ith column of per-atom array calculated by a compute with ID, I can include wildcard (see below)
f_ID = per-atom vector calculated by a fix with ID
f_ID\[I\] = Ith column of per-atom array calculated by a fix with ID, I can include wildcard (see below)
v_name = per-atom vector calculated by an atom-style variable with name
d_name = per-atom floating point vector with name, managed by fix property/atom
i_name = per-atom integer vector with name, managed by fix property/atom :pre
{local} args = list of local attributes :l
possible attributes = index, c_ID, c_ID\[I\], f_ID, f_ID\[I\]
index = enumeration of local values
c_ID = local vector calculated by a compute with ID
c_ID\[I\] = Ith column of local array calculated by a compute with ID, I can include wildcard (see below)
f_ID = local vector calculated by a fix with ID
f_ID\[I\] = Ith column of local array calculated by a fix with ID, I can include wildcard (see below) :pre
:ule
[Examples:]
dump myDump all atom 100 dump.atom
dump myDump all atom/mpiio 100 dump.atom.mpiio
dump myDump all atom/gz 100 dump.atom.gz
dump 2 subgroup atom 50 dump.run.bin
dump 2 subgroup atom 50 dump.run.mpiio.bin
dump 4a all custom 100 dump.myforce.* id type x y vx fx
dump 4b flow custom 100 dump.%.myforce id type c_myF\[3\] v_ke
dump 4b flow custom 100 dump.%.myforce id type c_myF\[*\] v_ke
dump 2 inner cfg 10 dump.snap.*.cfg mass type xs ys zs vx vy vz
dump snap all cfg 100 dump.config.*.cfg mass type xs ys zs id type c_Stress\[2\]
dump 1 all xtc 1000 file.xtc :pre
[Description:]
Dump a snapshot of atom quantities to one or more files every 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
combines and compresses them into a movie file; both are discussed in
detail on the "dump image"_dump_image.html doc page. The timesteps on
which dump output is written can also be controlled by a variable.
See the "dump_modify every"_dump_modify.html command.
Only information for atoms in the specified group is dumped. The
"dump_modify thresh and region and refresh"_dump_modify.html commands
can also alter what atoms are included. Not all styles support all
these options; see details on the "dump_modify"_dump_modify.html 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
or multiple smaller files).
NOTE: Because periodic boundary conditions are enforced only on
timesteps when neighbor lists are rebuilt, the coordinates of an atom
written to a dump file may be slightly outside the simulation box.
Re-neighbor timesteps will not typically coincide with the timesteps
dump snapshots are written. See the "dump_modify
pbc"_dump_modify.html command if you with to force coordinates to be
strictly inside the simulation box.
NOTE: Unless the "dump_modify sort"_dump_modify.html option is
invoked, the lines of atom information written to dump files
(typically one line per atom) will be in an indeterminate order for
each snapshot. This is even true when running on a single processor,
if the "atom_modify sort"_atom_modify.html option is on, which it is
by default. In this case atoms are re-ordered periodically during a
simulation, due to spatial sorting. It is also true when running in
parallel, because data for a single snapshot is collected from
multiple processors, each of which owns a subset of the atoms.
For the {atom}, {custom}, {cfg}, and {local} styles, sorting is off by
default. For the {dcd}, {xtc}, {xyz}, and {molfile} styles, sorting by
atom ID is on by default. See the "dump_modify"_dump_modify.html doc
page for details.
The {atom/gz}, {cfg/gz}, {custom/gz}, and {xyz/gz} styles are identical
in command syntax to the corresponding styles without "gz", however,
they generate compressed files using the zlib library. Thus the filename
suffix ".gz" is mandatory. This is an alternative approach to writing
compressed files via a pipe, as done 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 doc page, you should thus consider the {atom}
and {atom/gz} styles (etc) to be inter-changeable, with the exception
of the required filename suffix.
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
parallel via the MPI-IO library. For the remainder of this doc page,
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.
The precision of values output to text-based dump files can be
controlled by the "dump_modify format"_dump_modify.html command and
its options.
:line
The {style} keyword determines what atom quantities are written to the
file and in what format. Settings made via the
"dump_modify"_dump_modify.html command can also alter the format of
individual values and the file itself.
The {atom}, {local}, and {custom} styles create files in a simple text
format that is self-explanatory when viewing a dump file. Many of the
LAMMPS "post-processing tools"_Section_tools.html, including
"Pizza.py"_http://www.sandia.gov/~sjplimp/pizza.html, work with this
format, as does the "rerun"_rerun.html command.
For post-processing purposes the {atom}, {local}, and {custom} text
files are self-describing in the following sense.
The dimensions of the simulation box are included in each snapshot.
For an orthogonal simulation box this information is is formatted as:
ITEM: BOX BOUNDS xx yy zz
xlo xhi
ylo yhi
zlo zhi :pre
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
"boundary"_boundary.html 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,
formatted as follows:
ITEM: BOX BOUNDS xy xz yz xx yy zz
xlo_bound xhi_bound xy
ylo_bound yhi_bound xz
zlo_bound zhi_bound yz :pre
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.
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.
Note that the first two numbers on each line are now xlo_bound instead
of xlo, etc, since they represent a bounding box. See "this
section"_Section_howto.html#howto_12 of the doc pages 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 parameters, and how to transform those
parameters to and from other commonly used triclinic representations.
The "ITEM: ATOMS" line in each snapshot lists column descriptors for
the per-atom lines that follow. For example, the descriptors would be
"id type xs ys zs" for the default {atom} style, and would be the atom
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
boundaries. The format can be changed to unscaled coords via the
"dump_modify"_dump_modify.html settings. Image flags can also be
added for each atom via dump_modify.
Style {custom} allows you to specify a list of atom attributes to be
written to the dump file for each atom. Possible attributes are
listed above and will appear in the order specified. You cannot
specify a quantity that is not defined for a particular simulation -
such as {q} for atom style {bond}, since that atom style doesn't
assign charges. Dumps occur at the very end of a timestep, so atom
attributes will include effects due to fixes that are applied during
the timestep. An explanation of the possible dump custom attributes
is given below.
For style {local}, local output generated by "computes"_compute.html
and "fixes"_fix.html 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
of the possible dump local attributes is given below. Note that by
using input from the "compute
property/local"_compute_property_local.html command with dump local,
it is possible to generate information on bonds, angles, etc that can
be cut and pasted directly into a data file read by the
"read_data"_read_data.html command.
Style {cfg} has the same command syntax as style {custom} and writes
extended CFG format files, as used by the
"AtomEye"_http://mt.seas.upenn.edu/Archive/Graphics/A visualization
package. Since the extended CFG format uses a single snapshot of the
system per file, a wildcard "*" must be included in the filename, as
discussed below. The list of atom attributes for style {cfg} must
begin with either "mass type xs ys zs" or "mass type xsu ysu zsu"
since these quantities are needed to write the CFG files in the
appropriate format (though the "mass" and "type" fields do not appear
explicitly in the file). Any remaining attributes will be stored as
"auxiliary properties" in the CFG files. Note that you will typically
want to use the "dump_modify element"_dump_modify.html command with
CFG-formatted files, to associate element names with atom types, so
that AtomEye can render atoms appropriately. When unwrapped
coordinates {xsu}, {ysu}, and {zsu} are requested, the nominal AtomEye
periodic cell dimensions are expanded by a large factor UNWRAPEXPAND =
10.0, which ensures atoms that are displayed correctly for up to
UNWRAPEXPAND/2 periodic boundary crossings in any direction. Beyond
this, AtomEye will rewrap the unwrapped coordinates. The expansion
causes the atoms to be drawn farther away from the viewer, but it is
easy to zoom the atoms closer, and the interatomic distances are
unaffected.
The {dcd} style writes DCD files, a standard atomic trajectory format
used by the CHARMM, NAMD, and XPlor molecular dynamics packages. DCD
files are binary and thus may not be portable to different machines.
The number of atoms per snapshot cannot change with the {dcd} style.
The {unwrap} option of the "dump_modify"_dump_modify.html command
allows DCD coordinates to be written "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 these coordinates may thus be far outside
the box size stored with the snapshot.
The {xtc} style writes XTC files, a compressed trajectory format used
by the GROMACS molecular dynamics package, and described
"here"_http://manual.gromacs.org/current/online/xtc.html.
The precision used in XTC files can be adjusted via the
"dump_modify"_dump_modify.html command. The default value of 1000
means that coordinates are stored to 1/1000 nanometer accuracy. XTC
files are portable binary files written in the NFS XDR data format,
so that any machine which supports XDR should be able to read them.
The number of atoms per snapshot cannot change with the {xtc} style.
The {unwrap} option of the "dump_modify"_dump_modify.html command allows
XTC coordinates to be written "unwrapped" by the image flags for each
atom. Unwrapped means that if the atom has passed thru 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 these coordinates may thus be far outside the box size
stored with the snapshot.
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
"dump_modify element"_dump_modify.html 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.
Note that {atom}, {custom}, {dcd}, {xtc}, and {xyz} style dump files
can be read directly by "VMD"_http://www.ks.uiuc.edu/Research/vmd, a
popular molecular viewing program.
:line
Dumps are performed on timesteps that are a multiple of 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
changed via the "dump_modify first"_dump_modify.html 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
using the "dump_modify every"_dump_modify.html command (not allowed
for {dcd} style). The "dump_modify every"_dump_modify.html command
also allows a variable to be used to determine the sequence of
timesteps on which dump files are written. In this mode a dump on the
first timestep of a run will also not be written unless the
"dump_modify first"_dump_modify.html command is used.
The specified filename determines how the dump file(s) is written.
The default is to write one large text file, which is opened when the
dump command is invoked and closed when an "undump"_undump.html
command is used or when LAMMPS exits. For the {dcd} and {xtc} styles,
this is a single large binary file.
Dump filenames can contain two wildcard characters. If a "*"
character appears in the filename, then one file per snapshot is
written and the "*" character is replaced with the timestep value.
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 "dump_modify pad"_dump_modify.html
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
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}, and {xyz} 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
{fileper} keywords of the "dump_modify"_dump_modify.html command.
These options can be the most efficient way of writing out dump files
when running on large numbers of processors.
Note that using the "*" and "%" characters together can produce a
large number of small dump files!
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.
make yes-mpiio # installs the MPIIO package
make mpi # build LAMMPS for your platform :pre
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
counterparts. This means you can write a dump file using MPI-IO and
use the "read_dump"_read_dump.html command or perform other
post-processing, just as if the dump file was not written using
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" 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", 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 "binary2txt
tool"_Section_tools.html#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.
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.
:line
Note that in the discussion which follows, for styles which can
reference values from a compute or fix, like the {custom}, {cfg}, or
{local} styles, the bracketed index 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
size of the vector (for {mode} = scalar) or the number of columns in
the array (for {mode} = vector), then an asterisk with no numeric
values means all indices from 1 to 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 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
equivalent, since the "compute stress/atom"_compute_stress_atom.html
command creates a per-atom array with 6 columns:
compute myPress all stress/atom NULL
dump 2 all custom 100 tmp.dump id myPress\[*\]
dump 2 all custom 100 tmp.dump id myPress\[1\] myPress\[2\] myPress\[3\] &
myPress\[4\] myPress\[5\] myPress\[6\] :pre
:line
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
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.
The {c_ID} and {c_ID\[I\]} attributes allow local vectors or arrays
calculated by a "compute"_compute.html to be output. The ID in the
attribute should be replaced by the actual ID of the compute that has
been defined previously in the input script. See the
"compute"_compute.html command for details. There are computes for
calculating local information such as indices, types, and energies for
bonds and angles.
Note that computes which calculate global or per-atom quantities, as
opposed to local quantities, cannot be output in a dump local command.
Instead, global quantities can be output by the "thermo_style
custom"_thermo_style.html 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
specify multiple values.
The {f_ID} and {f_ID\[I\]} attributes allow local vectors or arrays
calculated by a "fix"_fix.html to be output. The ID in the attribute
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.
Here is an example of how to dump bond info for a system, including
the distance and energy of each bond:
compute 1 all property/local batom1 batom2 btype
compute 2 all bond/local dist eng
dump 1 all local 1000 tmp.dump index c_1\[1\] c_1\[2\] c_1\[3\] c_2\[1\] c_2\[2\] :pre
:line
This section explains the atom attributes that can be specified as
part of the {custom} and {cfg} styles.
The {id}, {mol}, {proc}, {procp1}, {type}, {element}, {mass}, {vx},
{vy}, {vz}, {fx}, {fy}, {fz}, {q} attributes are self-explanatory.
{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 "dump_modify
element"_dump_modify.html 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.
There are several options for outputting atom coordinates. The {x},
{y}, {z} attributes write atom coordinates "unscaled", in the
appropriate distance "units"_units.html (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
in "Section 6.12"_Section_howto.html#howto_12.
Use {xu}, {yu}, {zu} if you want the coordinates "unwrapped" by the
image flags for each atom. Unwrapped means that if the atom has
passed thru 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
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
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}
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
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
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.
The {radius} and {diameter} attributes are specific to spherical
particles that have a finite size, such as those defined with an atom
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.
The {angmomx}, {angmomy}, and {angmomz} attributes are specific to
finite-size aspherical particles that have an angular momentum. Only
the {ellipsoid} atom style defines this quantity.
The {tqx}, {tqy}, {tqz} attributes are for finite-size particles that
can sustain a rotational torque due to interactions with other
particles.
The {c_ID} and {c_ID\[I\]} attributes allow per-atom vectors or arrays
calculated by a "compute"_compute.html to be output. The ID in the
attribute should be replaced by the actual ID of the compute that has
been defined previously in the input script. See the
"compute"_compute.html command for details. There are computes for
calculating the per-atom energy, stress, centro-symmetry parameter,
and coordination number of individual atoms.
Note that computes which calculate global or local quantities, as
opposed to per-atom quantities, cannot be output in a dump custom
command. Instead, global quantities can be output by the
"thermo_style custom"_thermo_style.html command, and local quantities
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
effectively specify multiple values.
The {f_ID} and {f_ID\[I\]} attributes allow vector or array per-atom
quantities calculated by a "fix"_fix.html to be output. The ID in the
attribute should be replaced by the actual ID of the fix that has been
defined previously in the input script. The "fix
ave/atom"_fix_ave_atom.html command is one that calculates per-atom
quantities. Since it can time-average per-atom quantities produced by
any "compute"_compute.html, "fix"_fix.html, or atom-style
"variable"_variable.html, this allows those time-averaged results to
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.
The {v_name} attribute allows per-atom vectors calculated by a
"variable"_variable.html to be output. The name in the attribute
should be replaced by the actual name of the variable that has been
defined previously in the input script. Only an atom-style variable
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 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.
The {d_name} and {i_name} attributes allow to output custom per atom
floating point or integer properties that are managed by
"fix property/atom"_fix_property_atom.html.
See "Section 10"_Section_modify.html of the manual for information
on how to add new compute and fix styles to LAMMPS to calculate
per-atom quantities which could then be output into dump files.
:line
[Restrictions:]
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 "Making LAMMPS"_Section_start.html#start_2 section of
the documentation.
The {atom/gz}, {cfg/gz}, {custom/gz}, and {xyz/gz} styles are part
of the COMPRESS package. They are only enabled if LAMMPS was built
with that package. See the "Making
LAMMPS"_Section_start.html#start_3 section for more info.
The {atom/mpiio}, {cfg/mpiio}, {custom/mpiio}, and {xyz/mpiio} styles
are part of the MPIIO package. They are only enabled if LAMMPS was
built with that package. See the "Making
LAMMPS"_Section_start.html#start_3 section for more info.
The {xtc} style is part of the MISC package. It is only enabled if
LAMMPS was built with that package. See the "Making
LAMMPS"_Section_start.html#start_3 section for more info.
[Related commands:]
"dump h5md"_dump_h5md.html, "dump image"_dump_image.html,
"dump molfile"_dump_molfile.html, "dump_modify"_dump_modify.html,
"undump"_undump.html
[Default:]
The defaults for the {image} and {movie} styles are listed on the
"dump image"_dump_image.html doc page.

1090
doc/dump_modify.txt Normal file
View File

File diff suppressed because it is too large Load Diff

56
doc/reset_ids.txt Normal file
View File

@ -0,0 +1,56 @@
"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)
:line
reset_ids command :h3
[Syntax:]
reset_ids :pre
[Examples:]
reset_ids :pre
[Description:]
Reset atom IDs for the system, including all the global IDs stored
for bond, angle, dihedral, improper topology data. This will
create a set of IDs that are numbered contiguously from 1 to N
for a N atoms system.
This can be useful to do after perfoming a "delete_atoms" command for
a molecular system. The delete_atoms compress yes option will not
perform this operation due to the existence of bond topology. It can
also be useful to do after any simulation which has lost atoms,
e.g. due to atoms moving outside a simulation box with fixed
boundaries (see the "boundary command"), or due to evaporation (see
the "fix evaporate" command).
Note that the resetting of IDs is not really a compression, where gaps
in atom IDs are removed by decrementing atom IDs that are larger.
Instead the IDs for all atoms are erased, and new IDs are assigned so
that the atoms owned by an individual processor have consecutive IDs,
as the "create_atoms"_create_atoms.html command explains.
NOTE: If this command is used before a "pair style"_pair_style.html is
defined, an error about bond topology atom IDs not being found may
result. This is because the cutoff distance for ghost atom
communication was not sufficient to find atoms in bonds, angles, etc
that are owned by other processors. The "comm_modify
cutoff"_comm_modify.html command can be used to correct this issue.
Or you can define a pair style before using this command. If you do
the former, you should unset the comm_modify cutoff after using
reset_ids so that subsequent communication is not inefficient.
[Restrictions:] none
[Related commands:]
"delete_atoms"_delete_atoms.html
[Default:] none

3
src/atom.h
View File

@ -187,7 +187,8 @@ class Atom : protected Pointers {
int nextra_store;
int map_style; // style of atom map: 0=none, 1=array, 2=hash
int map_user; // user selected style = same 0,1,2
int map_user; // user requested map style:
// 0 = no request, 1=array, 2=hash, 3=yes
tagint map_tag_max; // max atom ID that map() is setup for
// spatial sorting of atoms

7
src/delete_atoms.cpp
View File

@ -22,13 +22,13 @@
#include "force.h"
#include "group.h"
#include "region.h"
#include "modify.h"
#include "neighbor.h"
#include "neigh_list.h"
#include "neigh_request.h"
#include "random_mars.h"
#include "memory.h"
#include "error.h"
#include "modify.h"
#include <map>
@ -68,7 +68,8 @@ void DeleteAtoms::command(int narg, char **arg)
if (allflag) {
int igroup = group->find("all");
if ((igroup >= 0) && modify->check_rigid_group_overlap(group->bitmask[igroup]))
if ((igroup >= 0) &&
modify->check_rigid_group_overlap(group->bitmask[igroup]))
error->warning(FLERR,"Attempting to delete atoms in rigid bodies");
} else {
if (modify->check_rigid_list_overlap(dlist))
@ -105,7 +106,7 @@ void DeleteAtoms::command(int narg, char **arg)
memory->destroy(dlist);
}
// if non-molecular system and compress flag set,
// if non-molecular system and compress flag set:
// reset atom tags to be contiguous
// set all atom IDs to 0, call tag_extend()

12
src/dump.cpp
View File

@ -85,6 +85,7 @@ Dump::Dump(LAMMPS *lmp, int narg, char **arg) : Pointers(lmp)
buffer_flag = 0;
padflag = 0;
pbcflag = 0;
delay_flag = 0;
maxbuf = maxids = maxsort = maxproc = 0;
buf = bufsort = NULL;
@ -304,6 +305,10 @@ void Dump::write()
imageint *imagehold;
double **xhold,**vhold;
// if timestep < delaystep, just return
if (delay_flag && update->ntimestep < delaystep) return;
// if file per timestep, open new file
if (multifile) openfile();
@ -876,6 +881,13 @@ void Dump::modify_params(int narg, char **arg)
error->all(FLERR,"Dump_modify buffer yes not allowed for this style");
iarg += 2;
} else if (strcmp(arg[iarg],"delay") == 0) {
if (iarg+2 > narg) error->all(FLERR,"Illegal dump_modify command");
delaystep = force->bnumeric(FLERR,arg[iarg+1]);
if (delaystep >= 0) delay_flag = 1;
else delay_flag = 0;
iarg += 2;
} else if (strcmp(arg[iarg],"every") == 0) {
if (iarg+2 > narg) error->all(FLERR,"Illegal dump_modify command");
int idump;

2
src/dump.h
View File

@ -77,6 +77,8 @@ class Dump : protected Pointers {
int sortcol; // 0 to sort on ID, 1-N on columns
int sortcolm1; // sortcol - 1
int sortorder; // ASCEND or DESCEND
int delay_flag; // 1 if delay output until delaystep
bigint delaystep;
char boundstr[9]; // encoding of boundary flags

5
src/read_dump.cpp
View File

@ -577,13 +577,14 @@ int ReadDump::fields_and_keywords(int narg, char **arg)
fieldlabel = new char*[narg+2];
// add id and type fields as needed
// scan ahead to see if "add yes" keyword/value is used
// scan ahead to see if "add yes/keep" keyword/value is used
// requires extra "type" field from from dump file
int iarg;
for (iarg = 0; iarg < narg; iarg++)
if (strcmp(arg[iarg],"add") == 0)
if (iarg < narg-1 && strcmp(arg[iarg+1],"yes") == 0) break;
if (iarg < narg-1 && (strcmp(arg[iarg+1],"yes") == 0 ||
strcmp(arg[iarg+1],"keep") == 0)) break;
nfield = 0;
fieldtype[nfield++] = ID;

246
src/reset_ids.cpp Normal file
View File

@ -0,0 +1,246 @@
/* ----------------------------------------------------------------------
LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator
http://lammps.sandia.gov, Sandia National Laboratories
Steve Plimpton, sjplimp@sandia.gov
Copyright (2003) Sandia Corporation. Under the terms of Contract
DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains
certain rights in this software. This software is distributed under
the GNU General Public License.
See the README file in the top-level LAMMPS directory.
------------------------------------------------------------------------- */
#include "reset_ids.h"
#include "atom.h"
#include "atom_vec.h"
#include "domain.h"
#include "comm.h"
#include "memory.h"
#include "error.h"
using namespace LAMMPS_NS;
/* ---------------------------------------------------------------------- */
ResetIDs::ResetIDs(LAMMPS *lmp) : Pointers(lmp) {}
/* ---------------------------------------------------------------------- */
void ResetIDs::command(int narg, char **arg)
{
if (domain->box_exist == 0)
error->all(FLERR,"Reset_ids command before simulation box is defined");
if (narg != 0) error->all(FLERR,"Illegal reset_ids command");
if (atom->tag_enable == 0)
error->all(FLERR,"Cannot use reset_ids unless atoms have IDs");
// NOTE: check if any fixes exist which store atom IDs?
// if so, this operation will mess up the fix
if (comm->me == 0) {
if (screen) fprintf(screen,"Resetting atom IDs ...\n");
if (logfile) fprintf(logfile,"Resetting atom IDs ...\n");
}
// create an atom map if one doesn't exist already
int mapflag = 0;
if (atom->map_style == 0) {
mapflag = 1;
atom->nghost = 0;
atom->map_init();
atom->map_set();
}
// initialize system since comm->borders() will be invoked
lmp->init();
// setup domain, communication
// acquire ghosts - is that really necessary?
// exchange will clear map, borders will reset
// this is the map needed to lookup current global IDs for bond topology
if (domain->triclinic) domain->x2lamda(atom->nlocal);
domain->pbc();
domain->reset_box();
comm->setup();
comm->exchange();
comm->borders();
if (domain->triclinic) domain->lamda2x(atom->nlocal+atom->nghost);
// oldIDs = copy of current owned IDs
tagint *tag = atom->tag;
int nlocal = atom->nlocal;
int nall = nlocal + atom->nghost;
tagint *oldIDs;
memory->create(oldIDs,nlocal,"reset_ids:oldIDs");
for (int i = 0; i < nlocal; i++) {
oldIDs[i] = tag[i];
tag[i] = 0;
}
// assign new contigous IDs to owned atoms via tag_extend()
atom->tag_extend();
// newIDs = copy of new IDs
// restore old IDs, consistent with existing atom map
// forward_comm_array acquires new IDs for ghost atoms
double **newIDs;
memory->create(newIDs,nall,1,"reset_ids:newIDs");
for (int i = 0; i < nlocal; i++) {
newIDs[i][0] = tag[i];
tag[i] = oldIDs[i];
}
comm->forward_comm_array(1,newIDs);
// loop over bonds, angles, etc and reset IDs in stored topology arrays
// only necessary for molecular = 1, not molecular = 2
// badcount = atom IDs that could not be found
int badcount = 0;
if (atom->molecular == 1) {
int j,m;
tagint oldID;
if (atom->avec->bonds_allow) {
int *num_bond = atom->num_bond;
tagint **bond_atom = atom->bond_atom;
for (int i = 0; i < nlocal; i++) {
for (j = 0; j < num_bond[i]; j++) {
oldID = bond_atom[i][j];
m = atom->map(oldID);
if (m >= 0) bond_atom[i][j] = static_cast<tagint> (newIDs[m][0]);
else badcount++;
}
}
}
if (atom->avec->angles_allow) {
int *num_angle = atom->num_angle;
tagint **angle_atom1 = atom->angle_atom1;
tagint **angle_atom2 = atom->angle_atom2;
tagint **angle_atom3 = atom->angle_atom3;
for (int i = 0; i < nlocal; i++) {
for (j = 0; j < num_angle[i]; j++) {
oldID = angle_atom1[i][j];
m = atom->map(oldID);
if (m >= 0) angle_atom1[i][j] = static_cast<tagint> (newIDs[m][0]);
else badcount++;
oldID = angle_atom2[i][j];
m = atom->map(oldID);
if (m >= 0) angle_atom2[i][j] = static_cast<tagint> (newIDs[m][0]);
else badcount++;
oldID = angle_atom3[i][j];
m = atom->map(oldID);
if (m >= 0) angle_atom3[i][j] = static_cast<tagint> (newIDs[m][0]);
else badcount++;
}
}
}
if (atom->avec->dihedrals_allow) {
int *num_dihedral = atom->num_dihedral;
tagint **dihedral_atom1 = atom->dihedral_atom1;
tagint **dihedral_atom2 = atom->dihedral_atom2;
tagint **dihedral_atom3 = atom->dihedral_atom3;
tagint **dihedral_atom4 = atom->dihedral_atom4;
for (int i = 0; i < nlocal; i++) {
for (j = 0; j < num_dihedral[i]; j++) {
oldID = dihedral_atom1[i][j];
m = atom->map(oldID);
if (m >= 0) dihedral_atom1[i][j] = static_cast<tagint> (newIDs[m][0]);
else badcount++;
oldID = dihedral_atom2[i][j];
m = atom->map(oldID);
if (m >= 0) dihedral_atom2[i][j] = static_cast<tagint> (newIDs[m][0]);
else badcount++;
oldID = dihedral_atom3[i][j];
m = atom->map(oldID);
if (m >= 0) dihedral_atom3[i][j] = static_cast<tagint> (newIDs[m][0]);
else badcount++;
oldID = dihedral_atom4[i][j];
m = atom->map(oldID);
if (m >= 0) dihedral_atom4[i][j] = static_cast<tagint> (newIDs[m][0]);
else badcount++;
}
}
}
if (atom->avec->impropers_allow) {
int *num_improper = atom->num_improper;
tagint **improper_atom1 = atom->improper_atom1;
tagint **improper_atom2 = atom->improper_atom2;
tagint **improper_atom3 = atom->improper_atom3;
tagint **improper_atom4 = atom->improper_atom4;
for (int i = 0; i < nlocal; i++) {
for (j = 0; j < num_improper[i]; j++) {
oldID = improper_atom1[i][j];
m = atom->map(oldID);
if (m >= 0) improper_atom1[i][j] = static_cast<tagint> (newIDs[m][0]);
else badcount++;
oldID = improper_atom2[i][j];
m = atom->map(oldID);
if (m >= 0) improper_atom2[i][j] = static_cast<tagint> (newIDs[m][0]);
else badcount++;
oldID = improper_atom3[i][j];
m = atom->map(oldID);
if (m >= 0) improper_atom3[i][j] = static_cast<tagint> (newIDs[m][0]);
else badcount++;
oldID = improper_atom4[i][j];
m = atom->map(oldID);
if (m >= 0) improper_atom4[i][j] = static_cast<tagint> (newIDs[m][0]);
else badcount++;
}
}
}
}
// error check
int all;
MPI_Allreduce(&badcount,&all,1,MPI_INT,MPI_SUM,world);
if (all) {
char str[128];
sprintf(str,"Reset_ids missing %d bond topology atom IDs - "
"use comm_modify cutoff",all);
error->all(FLERR,str);
}
// reset IDs and atom map for owned atoms
atom->map_clear();
atom->nghost = 0;
for (int i = 0; i < nlocal; i++) tag[i] = static_cast<tagint> (newIDs[i][0]);
atom->map_init();
atom->map_set();
// delete temporary atom map
if (mapflag) {
atom->map_delete();
atom->map_style = 0;
}
// clean up
memory->destroy(oldIDs);
memory->destroy(newIDs);
}

42
src/reset_ids.h Normal file
View File

@ -0,0 +1,42 @@
/* -*- c++ -*- ----------------------------------------------------------
LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator
http://lammps.sandia.gov, Sandia National Laboratories
Steve Plimpton, sjplimp@sandia.gov
Copyright (2003) Sandia Corporation. Under the terms of Contract
DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains
certain rights in this software. This software is distributed under
the GNU General Public License.
See the README file in the top-level LAMMPS directory.
------------------------------------------------------------------------- */
#ifdef COMMAND_CLASS
CommandStyle(reset_ids,ResetIDs)
#else
#ifndef LMP_RESET_IDS_H
#define LMP_RESET_IDS_H
#include "pointers.h"
namespace LAMMPS_NS {
class ResetIDs : protected Pointers {
public:
ResetIDs(class LAMMPS *);
void command(int, char **);
private:
};
}
#endif
#endif
/* ERROR/WARNING messages:
*/