forked from lijiext/lammps
310 lines
14 KiB
Plaintext
310 lines
14 KiB
Plaintext
"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
|
|
|
|
read_dump command :h3
|
|
|
|
[Syntax:]
|
|
|
|
read_dump file Nstep field1 field2 ... keyword values ... :pre
|
|
|
|
file = name of dump file to read :ulb,l
|
|
Nstep = snapshot timestep to read from file :l
|
|
one or more fields may be appended :l
|
|
field = {x} or {y} or {z} or {vx} or {vy} or {vz} or {ix} or {iy} or {iz}
|
|
{x},{y},{z} = atom coordinates
|
|
{vx},{vy},{vz} = velocity components
|
|
{ix},{iy},{iz} = image flags in each dimension :pre
|
|
zero or more keyword/value pairs may be appended :l
|
|
keyword = {box} or {replace} or {purge} or {trim} or {add} or {label} or {scaled} or {format} :l
|
|
{box} value = {yes} or {no} = replace simulation box with dump box
|
|
{replace} value = {yes} or {no} = overwrite atoms with dump atoms
|
|
{purge} value = {yes} or {no} = delete all atoms before adding dump atoms
|
|
{trim} value = {yes} or {no} = trim atoms not in dump snapshot
|
|
{add} value = {yes} or {no} = add new dump atoms to system
|
|
{label} value = field column
|
|
field = one of the listed fields or {id} or {type}
|
|
column = label on corresponding column in dump file
|
|
{scaled} value = {yes} or {no} = coords in dump file are scaled/unscaled
|
|
{format} values = format of dump file, must be last keyword if used
|
|
{native} = native LAMMPS dump file
|
|
{xyz} = XYZ file
|
|
{molfile} style path = VMD molfile plugin interface
|
|
style = {dcd} or {xyz} or others supported my mofile
|
|
path = optional path for location of molfile plugins :pre
|
|
:ule
|
|
|
|
[Examples:]
|
|
|
|
read_dump dump.file 5000 x y z
|
|
read_dump dump.file 5000 x y vx vy trim yes
|
|
read_dump ../run7/dump.file.gz 10000 x y z box yes
|
|
read_dump dump.xyz 5 x y z box no format xyz
|
|
read_dump dump.xyz 10 x y z box no format molfile xyz ../plugins
|
|
read_dump dump.dcd 0 x y z format molfile dcd
|
|
read_dump dump.file 1000 x y z vx vy vz format molfile lammpstrj /usr/local/lib/vmd/plugins/LINUXAMD64/plugins/molfile :pre
|
|
|
|
[Description:]
|
|
|
|
Read atom information from a dump file to overwrite the current atom
|
|
coordinates, and optionally the atom velocities and image flags and
|
|
the simluation box dimensions. This is useful for restarting a run
|
|
from a particular snapshot in a dump file. See the
|
|
"read_restart"_read_restart.html and "read_data"_read_data.html
|
|
commands and the "restart2data"_Section_tools.html#restart tool for
|
|
alternative methods to do this. Also see the "rerun"_rerun.html
|
|
command for a means of reading multiple snapshots from a dump file.
|
|
|
|
Note that a simulation box must already be defined before using the
|
|
read_dump command. This can be done by the
|
|
"create_box"_create_box.html, "read_data"_read_data.html, or
|
|
"read_restart"_read_restart.html commands. The read_dump command can
|
|
reset the simulation box dimensions, as explained below.
|
|
|
|
Also note that reading per-atom information from a dump snapshot is
|
|
limited to the atom coordinates, velocities and image flags, as
|
|
explained below. Other atom properties, which may be necessary to run
|
|
a valid simulation, such as atom charge, or bond topology information
|
|
for a molecular system, are not read from (or even contained in) dump
|
|
files. Thus this auxiliary information should be defined in the usual
|
|
way, e.g. in a data file read in by a "read_data"_read_data.html
|
|
command, before using the read_dump command, or by the "set"_set.html
|
|
command, after the dump snapshot is read.
|
|
|
|
:line
|
|
|
|
If the dump filename specified as {file} ends with ".gz", the dump
|
|
file is read in gzipped format. You cannot (yet) read a dump file
|
|
that was written in binary format with a ".bin" suffix, or to multiple
|
|
files via the "%" option in the dump file name. See the
|
|
"dump"_dump.html command for details.
|
|
|
|
The format of the dump file is selected through the {format} keyword.
|
|
If specified, it must be the last keyword used, since all remaining
|
|
arguments are passed on to the dump reader. The {native} format is
|
|
for native LAMMPS dump files, written with a "dump atom".html or "dump
|
|
custom"_dump.html command. The {xyz} format is for generic XYZ
|
|
formatted dump files,
|
|
|
|
The {molfile} format supports reading data through using the "VMD"_vmd
|
|
molfile plugin interface. This dump reader format is only available,
|
|
if the USER-MOLFILE package has been installed when compiling
|
|
LAMMPS.
|
|
|
|
The {molfile} format takes one or two additional values. The {style}
|
|
value determines the file format to be used and can be any format that
|
|
the molfile plugins support, such as DCD or XYZ. Note that DCD dump
|
|
files can be written by LAMMPS via the "dump dcd"_dump.html command.
|
|
The {path} value specifies a list of directories which LAMMPS will
|
|
search for the molfile plugins appropriate to the specified {style}.
|
|
The syntax of the {path} value is like other search paths: it can
|
|
contain multiple directories separated by a colon (or semi-colon on
|
|
windows). The {path} keyword is optional and defaults to ".",
|
|
i.e. the current directory.
|
|
|
|
Support for other dump format readers may be added in the future.
|
|
|
|
:line
|
|
|
|
Global information is first read from the dump file, namely timestep
|
|
and box information.
|
|
|
|
The dump file is scanned for a snapshot with a time stamp that matches
|
|
the specified {Nstep}. This means the LAMMPS timestep the dump file
|
|
snapshot was written on for the {native} format. However, the {xyz}
|
|
and {molfile} formats do not store the timestep. For these formats,
|
|
timesteps are numbered logically, in a sequential manner, starting
|
|
from 0. Thus to access the 10th snapshot in an {xyz} or {mofile}
|
|
formatted dump file, use {Nstep} = 9.
|
|
|
|
The dimensions of the simulation box for the selected snapshot are
|
|
also read; see the {box} keyword discussion below. For the {native}
|
|
format, an error is generated if the snapshot is for a triclinic box
|
|
and the current simulation box is orthogonal or vice versa. A warning
|
|
will be generated if the snapshot box boundary conditions (periodic,
|
|
shrink-wrapped, etc) do not match the current simulation boundary
|
|
conditions, but the boundary condition information in the snapshot is
|
|
otherwise ignored. See the "boundary" command for more details.
|
|
|
|
For the {xyz} format, no information about the box is available, so
|
|
you must set the {box} flag to {no}. See details below.
|
|
|
|
For the {molfile} format, reading simulation box information is
|
|
typically supported, but the location of the simulation box origin is
|
|
lost and no explicit information about periodicity or
|
|
orthogonal/triclinic box shape is available. The USER-MOLFILE package
|
|
makes a best effort to guess based on heuristics, but this may not
|
|
always work perfectly.
|
|
|
|
:line
|
|
|
|
Per-atom information from the dump file snapshot is then read from the
|
|
dump file snapshot. This corresponds tot the specified {fields}
|
|
listed in the read_dump command. It is an error to specify a
|
|
z-dimension field, namely {z}, {vz}, or {iz}, for a 2d simulation.
|
|
|
|
For dump files in {native} format, each column of per-atom data has a
|
|
text label listed in the file. A matching label for each field must
|
|
appear, e.g. the label "vy" for the field {vy}. For the {x}, {y}, {z}
|
|
fields any of the following labels are considered a match:
|
|
|
|
x, xs, xu, xsu for field {x}
|
|
y, ys, yu, ysu for field {y}
|
|
z, zs, zu, zsu for field {z} :pre
|
|
|
|
The meaning of xs (scaled), xu (unwrapped), and xsu (scaled and
|
|
unwrapped) is explained on the "dump"_dump.html command doc page.
|
|
These labels are searched for in the list of column labels in the dump
|
|
file, in order, until a match is found.
|
|
|
|
The dump file must also contain atom IDs, with a column label of "id".
|
|
|
|
If the {add} keyword is specified with a value of {yes}, as discussed
|
|
below, the dump file must contain atom types, with a column label of
|
|
"type".
|
|
|
|
If a column label in the dump file is not a match to a specified
|
|
field, the {label} keyword can be used to specify which column label
|
|
to associate with that field. An example is if a time-averaged
|
|
coordinate is written to the dump file via the "fix
|
|
ave/atom"_fix_ave_atom.html command. The column will then have a
|
|
label corresponding to the fix-ID rather than "x" or "xs". The
|
|
{label} keyword can also be used to specify new column labels for
|
|
fields {id} and {type}.
|
|
|
|
For dump files in {xyz} format, only the {x}, {y}, and {z} fields are
|
|
supported. The dump file does not store atom IDs, so these are
|
|
assigned consecutively to the atoms as they appear in the dump file,
|
|
starting from 1. Thus you should insure that order of atoms is
|
|
consistent from snapshot to snapshot in the the XYZ dump file. See
|
|
the "dump_modify sort"_dump_modify.html command if the XYZ dump file
|
|
was written by LAMMPS.
|
|
|
|
For dump files in {molfile} format, the {x}, {y}, {z}, {vx}, {vy}, and
|
|
{vz} fields can be specified. However, not all molfile formats store
|
|
velocities, or their respective plugins may not support reading of
|
|
velocities. The molfile dump files do not store atom IDs, so these
|
|
are assigned consecutively to the atoms as they appear in the dump
|
|
file, starting from 1. Thus you should insure that order of atoms are
|
|
consistent from snapshot to snapshot in the the molfile dump file.
|
|
See the "dump_modify sort"_dump_modify.html command if the dump file
|
|
was written by LAMMPS.
|
|
|
|
:line
|
|
|
|
Information from the dump file snapshot is used to overwrite or
|
|
replace properties of the current system. There are various options
|
|
for how this is done, determined by the specified fields and optional
|
|
keywords.
|
|
|
|
The timestep of the snapshot becomes the current timestep for the
|
|
simulation. See the "reset_timestep"_reset_timestep.html command if
|
|
you wish to change this after the dump snapshot is read.
|
|
|
|
If the {box} keyword is specified with a {yes} value, then the current
|
|
simulation box dimensions are replaced by the dump snapshot box
|
|
dimensions. If the {box} keyword is specified with a {no} value, the
|
|
current simulatoin box is unchanged.
|
|
|
|
If the {purge} keyword is specified with a {yes} value, then all
|
|
current atoms in the system are deleted before any of the operations
|
|
invoked by the {replace}, {trim}, or {add} keywords take place.
|
|
|
|
If the {replace} keyword is specified with a {yes} value, then atoms
|
|
with IDs that are in both the current system and the dump snapshot
|
|
have their properties overwritten by field values. If the {replace}
|
|
keyword is specified with a {no} value, atoms with IDs that are in
|
|
both the current system and the dump snapshot are not modified.
|
|
|
|
If the {trim} keyword is specified with a {yes} value, then atoms with
|
|
IDs that are in the current system but not in the dump snapshot are
|
|
deleted. These atoms are unaffected if the {trim} keyword is
|
|
specified with a {no} value.
|
|
|
|
If the {add} keyword is specified with a {yes} value, then atoms with
|
|
IDs that are in the dump snapshot, but not in the current system are
|
|
added to the system. These dump atoms are ignored if the {add}
|
|
keyword is specified with a {no} value.
|
|
|
|
Note that atoms added via the {add} keyword will have only the
|
|
attributes read from the dump file due to the {field} arguments. If
|
|
{x} or {y} or {z} is not specified as a field, a value of 0.0 is used
|
|
for added atoms. Added atoms must have an atom type, so this value
|
|
must appear in the dump file.
|
|
|
|
Any other attributes (e.g. charge or particle diameter for spherical
|
|
particles) will be set to default values, the same as if the
|
|
"create_atoms"_create_atoms.html command were used.
|
|
|
|
Note that atom IDs are not preserved for new dump snapshot atoms added
|
|
via the {add} keyword. The procedure for assigning new atom IDS to
|
|
added atoms is the same as is described for the
|
|
"create_atoms"_create_atoms.html command.
|
|
|
|
:line
|
|
|
|
Atom coordinates read from the dump file are converted into absolute,
|
|
unscaled coordinates, relative to the box dimensions of the snapshot.
|
|
These coordinates may then be assigned to an existing or new atom in
|
|
the current simulation. The coordinates will be remapped to the
|
|
simulation box, whether it is the original box or the dump snapshot
|
|
box. If periodic boundary conditiona apply, this means the atom will
|
|
be remapped back into the box if necessary. If shrink-wrap boundary
|
|
conditions apply, the new coordinates may change the current box
|
|
dimensions. If fixed boundary conditions apply, the atom will be lost
|
|
if it is outside the simulation box.
|
|
|
|
For {native} format dump files, the 3 xyz image flags for an atom in
|
|
the dump file are set to the corresponding values appearing in the
|
|
dump file if the {ix}, {iy}, {iz} fields are specified. If not
|
|
specified, the image flags for replaced atoms are not changed and
|
|
image flags for new atoms are set to default values. The remapping
|
|
procedure described in the previous paragraph can change images flags
|
|
for all atoms (old and new) if periodic boundary conditions are
|
|
applied to remap an atom back into the simulation box. Note that
|
|
inconsistent image flag values can result if you use image flag fields
|
|
from the dump file but do not also use the dump file box parameters.
|
|
|
|
LAMMPS knows how to compute absolute, unscaled coordinates for the
|
|
snapshot column labels discussed above, e.g. {x}, {xs}, {xu}, {xsu}.
|
|
If another column label is assigned to the {x} or {y} or {z} field via
|
|
the {label} keyword, e.g. for coordinates output by the "fix
|
|
ave/atom"_fix_ave_atom.html command, then LAMMPS needs to know whether
|
|
the coordinate information in the dump file is scaled or unscaled.
|
|
This can be set via the {scaled} keyword. The value of the {scaled}
|
|
keyword is ignored for field {x} or {y} or {z} if the {label} keyword
|
|
is not used to assign a column label to that field.
|
|
|
|
The scaled vs unscaled setting must be consistent for any of the {x},
|
|
{y}, {z} fields that are specified. If the dump file coordinates are
|
|
scaled and the simulation box is triclinic, then all 3 of the {x},
|
|
{y}, {z} fields must be specified, since they are all needed to
|
|
generate absolute, unscaled coordinates.
|
|
|
|
:line
|
|
|
|
[Restrictions:]
|
|
|
|
To read gzipped dump files, you must compile LAMMPS with the
|
|
-DLAMMPS_GZIP option - see the "Making
|
|
LAMMPS"_Section_start.html#start_2 section of the documentation.
|
|
|
|
The {molfile} dump file formats are part of the USER-MOLFILE package.
|
|
They are only enabled if LAMMPS was built with that packages. See the
|
|
"Making LAMMPS"_Section_start.html#start_3 section for more info.
|
|
|
|
[Related commands:]
|
|
|
|
"dump"_dump.html, "dump molfile"_dump_molfile.html,
|
|
"read_data"_read_data.html, "read_restart"_read_restart.html,
|
|
"rerun"_rerun.html
|
|
|
|
[Default:]
|
|
|
|
The option defaults are box = yes, replace = yes, purge = no, trim =
|
|
no, add = no, scaled = no, and format = native.
|