git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@16053 f3b2605a-c512-4ea7-a41b...
[lammps.git] / doc / src / dump.txt
blob5f8ee1ee88e2330049e50301addbb8a3c51cbcfc
1  "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
3 :link(lws,http://lammps.sandia.gov)
4 :link(ld,Manual.html)
5 :link(lc,Section_commands.html#comm)
7 :line
9 dump command :h3
10 "dump custom/vtk"_dump_custom_vtk.html command :h3
11 "dump h5md"_dump_h5md.html command :h3
12 "dump image"_dump_image.html command :h3
13 "dump movie"_dump_image.html command :h3
14 "dump molfile"_dump_molfile.html command :h3
15 "dump nc"_dump_nc.html command :h3
17 [Syntax:]
19 dump ID group-ID style N file args :pre
21 ID = user-assigned name for the dump :ulb,l
22 group-ID = ID of the group of atoms to be dumped :l
23 style = {atom} or {atom/gz} or {atom/mpiio} or {cfg} or {cfg/gz} or {cfg/mpiio} or {dcd} or {xtc} or {xyz} or {xyz/gz} or {xyz/mpiio} or {h5md} or {image} or {movie} or {molfile} or {local} or {custom} or {custom/gz} or {custom/mpiio} :l
24 N = dump every this many timesteps :l
25 file = name of file to write dump info to :l
26 args = list of arguments for a particular style :l
27   {atom} args = none
28   {atom/gz} args = none
29   {atom/mpiio} args = none
30   {cfg} args = same as {custom} args, see below
31   {cfg/gz} args = same as {custom} args, see below
32   {cfg/mpiio} args = same as {custom} args, see below
33   {dcd} args = none
34   {xtc} args = none
35   {xyz} args = none :pre
36   {xyz/gz} args = none :pre
37   {xyz/mpiio} args = none :pre
39   {custom/vtk} args = similar to custom args below, discussed on "dump custom/vtk"_dump_custom_vtk.html doc page :pre
41   {h5md} args = discussed on "dump h5md"_dump_h5md.html doc page :pre
43   {image} args = discussed on "dump image"_dump_image.html doc page :pre
45   {movie} args = discussed on "dump image"_dump_image.html doc page :pre
47   {molfile} args = discussed on "dump molfile"_dump_molfile.html doc page
49   {nc} args = discussed on "dump nc"_dump_nc.html doc page :pre
51   {local} args = list of local attributes
52     possible attributes = index, c_ID, c_ID\[I\], f_ID, f_ID\[I\]
53       index = enumeration of local values
54       c_ID = local vector calculated by a compute with ID
55       c_ID\[I\] = Ith column of local array calculated by a compute with ID, I can include wildcard (see below)
56       f_ID = local vector calculated by a fix with ID
57       f_ID\[I\] = Ith column of local array calculated by a fix with ID, I can include wildcard (see below) :pre
59   {custom} or {custom/gz} or {custom/mpiio} args = list of atom attributes
60     possible attributes = id, mol, proc, procp1, type, element, mass,
61                           x, y, z, xs, ys, zs, xu, yu, zu,
62                           xsu, ysu, zsu, ix, iy, iz,
63                           vx, vy, vz, fx, fy, fz,
64                           q, mux, muy, muz, mu,
65                           radius, diameter, omegax, omegay, omegaz,
66                           angmomx, angmomy, angmomz, tqx, tqy, tqz,
67                           c_ID, c_ID\[N\], f_ID, f_ID\[N\], v_name :pre
69       id = atom ID
70       mol = molecule ID
71       proc = ID of processor that owns atom
72       procp1 = ID+1 of processor that owns atom
73       type = atom type
74       element = name of atom element, as defined by "dump_modify"_dump_modify.html command
75       mass = atom mass
76       x,y,z = unscaled atom coordinates
77       xs,ys,zs = scaled atom coordinates
78       xu,yu,zu = unwrapped atom coordinates
79       xsu,ysu,zsu = scaled unwrapped atom coordinates
80       ix,iy,iz = box image that the atom is in
81       vx,vy,vz = atom velocities
82       fx,fy,fz = forces on atoms
83       q = atom charge
84       mux,muy,muz = orientation of dipole moment of atom
85       mu = magnitude of dipole moment of atom
86       radius,diameter = radius,diameter of spherical particle
87       omegax,omegay,omegaz = angular velocity of spherical particle
88       angmomx,angmomy,angmomz = angular momentum of aspherical particle
89       tqx,tqy,tqz = torque on finite-size particles
90       c_ID = per-atom vector calculated by a compute with ID
91       c_ID\[I\] = Ith column of per-atom array calculated by a compute with ID, I can include wildcard (see below)
92       f_ID = per-atom vector calculated by a fix with ID
93       f_ID\[I\] = Ith column of per-atom array calculated by a fix with ID, I can include wildcard (see below)
94       v_name = per-atom vector calculated by an atom-style variable with name
95       d_name = per-atom floating point vector with name, managed by fix property/atom
96       i_name = per-atom integer vector with name, managed by fix property/atom :pre
97 :ule
99 [Examples:]
101 dump myDump all atom 100 dump.atom
102 dump myDump all atom/mpiio 100 dump.atom.mpiio
103 dump myDump all atom/gz 100 dump.atom.gz
104 dump 2 subgroup atom 50 dump.run.bin
105 dump 2 subgroup atom 50 dump.run.mpiio.bin
106 dump 4a all custom 100 dump.myforce.* id type x y vx fx
107 dump 4b flow custom 100 dump.%.myforce id type c_myF\[3\] v_ke
108 dump 4b flow custom 100 dump.%.myforce id type c_myF\[*\] v_ke
109 dump 2 inner cfg 10 dump.snap.*.cfg mass type xs ys zs vx vy vz
110 dump snap all cfg 100 dump.config.*.cfg mass type xs ys zs id type c_Stress\[2\]
111 dump 1 all xtc 1000 file.xtc :pre
113 [Description:]
115 Dump a snapshot of atom quantities to one or more files every N
116 timesteps in one of several styles.  The {image} and {movie} styles are
117 the exception: the {image} style renders a JPG, PNG, or PPM image file
118 of the atom configuration every N timesteps while the {movie} style
119 combines and compresses them into a movie file; both are discussed in
120 detail on the "dump image"_dump_image.html doc page.  The timesteps on
121 which dump output is written can also be controlled by a variable.
122 See the "dump_modify every"_dump_modify.html command.
124 Only information for atoms in the specified group is dumped.  The
125 "dump_modify thresh and region"_dump_modify.html commands can also
126 alter what atoms are included.  Not all styles support all these
127 options; see details below.
129 As described below, the filename determines the kind of output (text
130 or binary or gzipped, one big file or one per timestep, one big file
131 or multiple smaller files).
133 NOTE: Because periodic boundary conditions are enforced only on
134 timesteps when neighbor lists are rebuilt, the coordinates of an atom
135 written to a dump file may be slightly outside the simulation box.
136 Re-neighbor timesteps will not typically coincide with the timesteps
137 dump snapshots are written.  See the "dump_modify
138 pbc"_dump_modify.html command if you with to force coordinates to be
139 strictly inside the simulation box.
141 NOTE: Unless the "dump_modify sort"_dump_modify.html option is
142 invoked, the lines of atom information written to dump files
143 (typically one line per atom) will be in an indeterminate order for
144 each snapshot.  This is even true when running on a single processor,
145 if the "atom_modify sort"_atom_modify.html option is on, which it is
146 by default.  In this case atoms are re-ordered periodically during a
147 simulation, due to spatial sorting.  It is also true when running in
148 parallel, because data for a single snapshot is collected from
149 multiple processors, each of which owns a subset of the atoms.
151 For the {atom}, {custom}, {cfg}, and {local} styles, sorting is off by
152 default.  For the {dcd}, {xtc}, {xyz}, and {molfile} styles, sorting by
153 atom ID is on by default. See the "dump_modify"_dump_modify.html doc
154 page for details.
156 The {atom/gz}, {cfg/gz}, {custom/gz}, and {xyz/gz} styles are identical
157 in command syntax to the corresponding styles without "gz", however,
158 they generate compressed files using the zlib library. Thus the filename
159 suffix ".gz" is mandatory. This is an alternative approach to writing
160 compressed files via a pipe, as done by the regular dump styles, which
161 may be required on clusters where the interface to the high-speed network
162 disallows using the fork() library call (which is needed for a pipe).
163 For the remainder of this doc page, you should thus consider the {atom}
164 and {atom/gz} styles (etc) to be inter-changeable, with the exception
165 of the required filename suffix.
167 As explained below, the {atom/mpiio}, {cfg/mpiio}, {custom/mpiio}, and
168 {xyz/mpiio} styles are identical in command syntax and in the format
169 of the dump files they create, to the corresponding styles without
170 "mpiio", except the single dump file they produce is written in
171 parallel via the MPI-IO library.  For the remainder of this doc page,
172 you should thus consider the {atom} and {atom/mpiio} styles (etc) to
173 be inter-changeable.  The one exception is how the filename is
174 specified for the MPI-IO styles, as explained below.
176 The precision of values output to text-based dump files can be
177 controlled by the "dump_modify format"_dump_modify.html command and
178 its options.
180 :line
182 The {style} keyword determines what atom quantities are written to the
183 file and in what format.  Settings made via the
184 "dump_modify"_dump_modify.html command can also alter the format of
185 individual values and the file itself.
187 The {atom}, {local}, and {custom} styles create files in a simple text
188 format that is self-explanatory when viewing a dump file.  Many of the
189 LAMMPS "post-processing tools"_Section_tools.html, including
190 "Pizza.py"_http://www.sandia.gov/~sjplimp/pizza.html, work with this
191 format, as does the "rerun"_rerun.html command.
193 For post-processing purposes the {atom}, {local}, and {custom} text
194 files are self-describing in the following sense.
196 The dimensions of the simulation box are included in each snapshot.
197 For an orthogonal simulation box this information is is formatted as:
199 ITEM: BOX BOUNDS xx yy zz
200 xlo xhi
201 ylo yhi
202 zlo zhi :pre
204 where xlo,xhi are the maximum extents of the simulation box in the
205 x-dimension, and similarly for y and z.  The "xx yy zz" represent 6
206 characters that encode the style of boundary for each of the 6
207 simulation box boundaries (xlo,xhi and ylo,yhi and zlo,zhi).  Each of
208 the 6 characters is either p = periodic, f = fixed, s = shrink wrap,
209 or m = shrink wrapped with a minimum value.  See the
210 "boundary"_boundary.html command for details.
212 For triclinic simulation boxes (non-orthogonal), an orthogonal
213 bounding box which encloses the triclinic simulation box is output,
214 along with the 3 tilt factors (xy, xz, yz) of the triclinic box,
215 formatted as follows:
217 ITEM: BOX BOUNDS xy xz yz xx yy zz
218 xlo_bound xhi_bound xy
219 ylo_bound yhi_bound xz
220 zlo_bound zhi_bound yz :pre
222 The presence of the text "xy xz yz" in the ITEM line indicates that
223 the 3 tilt factors will be included on each of the 3 following lines.
224 This bounding box is convenient for many visualization programs.  The
225 meaning of the 6 character flags for "xx yy zz" is the same as above.
227 Note that the first two numbers on each line are now xlo_bound instead
228 of xlo, etc, since they repesent a bounding box.  See "this
229 section"_Section_howto.html#howto_12 of the doc pages for a geometric
230 description of triclinic boxes, as defined by LAMMPS, simple formulas
231 for how the 6 bounding box extents (xlo_bound,xhi_bound,etc) are
232 calculated from the triclinic parameters, and how to transform those
233 parameters to and from other commonly used triclinic representations.
235 The "ITEM: ATOMS" line in each snapshot lists column descriptors for
236 the per-atom lines that follow.  For example, the descriptors would be
237 "id type xs ys zs" for the default {atom} style, and would be the atom
238 attributes you specify in the dump command for the {custom} style.
240 For style {atom}, atom coordinates are written to the file, along with
241 the atom ID and atom type.  By default, atom coords are written in a
242 scaled format (from 0 to 1).  I.e. an x value of 0.25 means the atom
243 is at a location 1/4 of the distance from xlo to xhi of the box
244 boundaries.  The format can be changed to unscaled coords via the
245 "dump_modify"_dump_modify.html settings.  Image flags can also be
246 added for each atom via dump_modify.
248 Style {custom} allows you to specify a list of atom attributes to be
249 written to the dump file for each atom.  Possible attributes are
250 listed above and will appear in the order specified.  You cannot
251 specify a quantity that is not defined for a particular simulation -
252 such as {q} for atom style {bond}, since that atom style doesn't
253 assign charges.  Dumps occur at the very end of a timestep, so atom
254 attributes will include effects due to fixes that are applied during
255 the timestep.  An explanation of the possible dump custom attributes
256 is given below.
258 For style {local}, local output generated by "computes"_compute.html
259 and "fixes"_fix.html is used to generate lines of output that is
260 written to the dump file.  This local data is typically calculated by
261 each processor based on the atoms it owns, but there may be zero or
262 more entities per atom, e.g. a list of bond distances.  An explanation
263 of the possible dump local attributes is given below.  Note that by
264 using input from the "compute
265 property/local"_compute_property_local.html command with dump local,
266 it is possible to generate information on bonds, angles, etc that can
267 be cut and pasted directly into a data file read by the
268 "read_data"_read_data.html command.
270 Style {cfg} has the same command syntax as style {custom} and writes
271 extended CFG format files, as used by the
272 "AtomEye"_http://mt.seas.upenn.edu/Archive/Graphics/A visualization
273 package.  Since the extended CFG format uses a single snapshot of the
274 system per file, a wildcard "*" must be included in the filename, as
275 discussed below.  The list of atom attributes for style {cfg} must
276 begin with either "mass type xs ys zs" or "mass type xsu ysu zsu"
277 since these quantities are needed to write the CFG files in the
278 appropriate format (though the "mass" and "type" fields do not appear
279 explicitly in the file).  Any remaining attributes will be stored as
280 "auxiliary properties" in the CFG files.  Note that you will typically
281 want to use the "dump_modify element"_dump_modify.html command with
282 CFG-formatted files, to associate element names with atom types, so
283 that AtomEye can render atoms appropriately. When unwrapped
284 coordinates {xsu}, {ysu}, and {zsu} are requested, the nominal AtomEye
285 periodic cell dimensions are expanded by a large factor UNWRAPEXPAND =
286 10.0, which ensures atoms that are displayed correctly for up to
287 UNWRAPEXPAND/2 periodic boundary crossings in any direction.  Beyond
288 this, AtomEye will rewrap the unwrapped coordinates.  The expansion
289 causes the atoms to be drawn farther away from the viewer, but it is
290 easy to zoom the atoms closer, and the interatomic distances are
291 unaffected.
293 The {dcd} style writes DCD files, a standard atomic trajectory format
294 used by the CHARMM, NAMD, and XPlor molecular dynamics packages.  DCD
295 files are binary and thus may not be portable to different machines.
296 The number of atoms per snapshot cannot change with the {dcd} style.
297 The {unwrap} option of the "dump_modify"_dump_modify.html command
298 allows DCD coordinates to be written "unwrapped" by the image flags
299 for each atom.  Unwrapped means that if the atom has passed through
300 a periodic boundary one or more times, the value is printed for what
301 the coordinate would be if it had not been wrapped back into the
302 periodic box.  Note that these coordinates may thus be far outside
303 the box size stored with the snapshot.
305 The {xtc} style writes XTC files, a compressed trajectory format used
306 by the GROMACS molecular dynamics package, and described
307 "here"_http://manual.gromacs.org/current/online/xtc.html.
308 The precision used in XTC files can be adjusted via the
309 "dump_modify"_dump_modify.html command.  The default value of 1000
310 means that coordinates are stored to 1/1000 nanometer accuracy.  XTC
311 files are portable binary files written in the NFS XDR data format,
312 so that any machine which supports XDR should be able to read them.
313 The number of atoms per snapshot cannot change with the {xtc} style.
314 The {unwrap} option of the "dump_modify"_dump_modify.html command allows
315 XTC coordinates to be written "unwrapped" by the image flags for each
316 atom.  Unwrapped means that if the atom has passed thru a periodic
317 boundary one or more times, the value is printed for what the
318 coordinate would be if it had not been wrapped back into the periodic
319 box.  Note that these coordinates may thus be far outside the box size
320 stored with the snapshot.
322 The {xyz} style writes XYZ files, which is a simple text-based
323 coordinate format that many codes can read. Specifically it has
324 a line with the number of atoms, then a comment line that is
325 usually ignored followed by one line per atom with the atom type
326 and the x-, y-, and z-coordinate of that atom. You can use the
327 "dump_modify element"_dump_modify.html option to change the output
328 from using the (numerical) atom type to an element name (or some
329 other label). This will help many visualization programs to guess
330 bonds and colors.
332 Note that {atom}, {custom}, {dcd}, {xtc}, and {xyz} style dump files
333 can be read directly by "VMD"_http://www.ks.uiuc.edu/Research/vmd, a
334 popular molecular viewing program.  See
335 "Section 9"_Section_tools.html#vmd of the manual and the
336 tools/lmp2vmd/README.txt file for more information about support in
337 VMD for reading and visualizing LAMMPS dump files.
339 :line
341 Dumps are performed on timesteps that are a multiple of N (including
342 timestep 0) and on the last timestep of a minimization if the
343 minimization converges.  Note that this means a dump will not be
344 performed on the initial timestep after the dump command is invoked,
345 if the current timestep is not a multiple of N.  This behavior can be
346 changed via the "dump_modify first"_dump_modify.html command, which
347 can also be useful if the dump command is invoked after a minimization
348 ended on an arbitrary timestep.  N can be changed between runs by
349 using the "dump_modify every"_dump_modify.html command (not allowed
350 for {dcd} style).  The "dump_modify every"_dump_modify.html command
351 also allows a variable to be used to determine the sequence of
352 timesteps on which dump files are written.  In this mode a dump on the
353 first timestep of a run will also not be written unless the
354 "dump_modify first"_dump_modify.html command is used.
356 The specified filename determines how the dump file(s) is written.
357 The default is to write one large text file, which is opened when the
358 dump command is invoked and closed when an "undump"_undump.html
359 command is used or when LAMMPS exits.  For the {dcd} and {xtc} styles,
360 this is a single large binary file.
362 Dump filenames can contain two wildcard characters.  If a "*"
363 character appears in the filename, then one file per snapshot is
364 written and the "*" character is replaced with the timestep value.
365 For example, tmp.dump.* becomes tmp.dump.0, tmp.dump.10000,
366 tmp.dump.20000, etc.  This option is not available for the {dcd} and
367 {xtc} styles.  Note that the "dump_modify pad"_dump_modify.html
368 command can be used to insure all timestep numbers are the same length
369 (e.g. 00010), which can make it easier to read a series of dump files
370 in order with some post-processing tools.
372 If a "%" character appears in the filename, then each of P processors
373 writes a portion of the dump file, and the "%" character is replaced
374 with the processor ID from 0 to P-1.  For example, tmp.dump.% becomes
375 tmp.dump.0, tmp.dump.1, ... tmp.dump.P-1, etc.  This creates smaller
376 files and can be a fast mode of output on parallel machines that
377 support parallel I/O for output. This option is not available for the
378 {dcd}, {xtc}, and {xyz} styles.
380 By default, P = the number of processors meaning one file per
381 processor, but P can be set to a smaller value via the {nfile} or
382 {fileper} keywords of the "dump_modify"_dump_modify.html command.
383 These options can be the most efficient way of writing out dump files
384 when running on large numbers of processors.
386 Note that using the "*" and "%" characters together can produce a
387 large number of small dump files!
389 For the {atom/mpiio}, {cfg/mpiio}, {custom/mpiio}, and {xyz/mpiio}
390 styles, a single dump file is written in parallel via the MPI-IO
391 library, which is part of the MPI standard for versions 2.0 and above.
392 Using MPI-IO requires two steps.  First, build LAMMPS with its MPIIO
393 package installed, e.g.
395 make yes-mpiio    # installs the MPIIO package
396 make mpi          # build LAMMPS for your platform :pre
398 Second, use a dump filename which contains ".mpiio".  Note that it
399 does not have to end in ".mpiio", just contain those characters.
400 Unlike MPI-IO restart files, which must be both written and read using
401 MPI-IO, the dump files produced by these MPI-IO styles are identical
402 in format to the files produced by their non-MPI-IO style
403 counterparts.  This means you can write a dump file using MPI-IO and
404 use the "read_dump"_read_dump.html command or perform other
405 post-processing, just as if the dump file was not written using
406 MPI-IO.
408 Note that MPI-IO dump files are one large file which all processors
409 write to.  You thus cannot use the "%" wildcard character described
410 above in the filename since that specifies generation of multiple
411 files.  You can use the ".bin" suffix described below in an MPI-IO
412 dump file; again this file will be written in parallel and have the
413 same binary format as if it were written without MPI-IO.
415 If the filename ends with ".bin", the dump file (or files, if "*" or
416 "%" is also used) is written in binary format.  A binary dump file
417 will be about the same size as a text version, but will typically
418 write out much faster.  Of course, when post-processing, you will need
419 to convert it back to text format (see the "binary2txt
420 tool"_Section_tools.html#binary) or write your own code to read the
421 binary file.  The format of the binary file can be understood by
422 looking at the tools/binary2txt.cpp file.  This option is only
423 available for the {atom} and {custom} styles.
425 If the filename ends with ".gz", the dump file (or files, if "*" or "%"
426 is also used) is written in gzipped format.  A gzipped dump file will
427 be about 3x smaller than the text version, but will also take longer
428 to write.  This option is not available for the {dcd} and {xtc}
429 styles.
431 :line
433 Note that in the discussion which follows, for styles which can
434 reference values from a compute or fix, like the {custom}, {cfg}, or
435 {local} styles, the bracketed index I can be specified using a
436 wildcard asterisk with the index to effectively specify multiple
437 values.  This takes the form "*" or "*n" or "n*" or "m*n".  If N = the
438 size of the vector (for {mode} = scalar) or the number of columns in
439 the array (for {mode} = vector), then an asterisk with no numeric
440 values means all indices from 1 to N.  A leading asterisk means all
441 indices from 1 to n (inclusive).  A trailing asterisk means all
442 indices from n to N (inclusive).  A middle asterisk means all indices
443 from m to n (inclusive).
445 Using a wildcard is the same as if the individual columns of the array
446 had been listed one by one.  E.g. these 2 dump commands are
447 equivalent, since the "compute stress/atom"_compute_stress_atom.html
448 command creates a per-atom array with 6 columns:
450 compute myPress all stress/atom NULL
451 dump 2 all custom 100 tmp.dump id myPress\[*\]
452 dump 2 all custom 100 tmp.dump id myPress\[1\] myPress\[2\] myPress\[3\] &
453                                   myPress\[4\] myPress\[5\] myPress\[6\] :pre
455 :line
457 This section explains the local attributes that can be specified as
458 part of the {local} style.
460 The {index} attribute can be used to generate an index number from 1
461 to N for each line written into the dump file, where N is the total
462 number of local datums from all processors, or lines of output that
463 will appear in the snapshot.  Note that because data from different
464 processors depend on what atoms they currently own, and atoms migrate
465 between processor, there is no guarantee that the same index will be
466 used for the same info (e.g. a particular bond) in successive
467 snapshots.
469 The {c_ID} and {c_ID\[I\]} attributes allow local vectors or arrays
470 calculated by a "compute"_compute.html to be output.  The ID in the
471 attribute should be replaced by the actual ID of the compute that has
472 been defined previously in the input script.  See the
473 "compute"_compute.html command for details.  There are computes for
474 calculating local information such as indices, types, and energies for
475 bonds and angles.
477 Note that computes which calculate global or per-atom quantities, as
478 opposed to local quantities, cannot be output in a dump local command.
479 Instead, global quantities can be output by the "thermo_style
480 custom"_thermo_style.html command, and per-atom quantities can be
481 output by the dump custom command.
483 If {c_ID} is used as a attribute, then the local vector calculated by
484 the compute is printed.  If {c_ID\[I\]} is used, then I must be in the
485 range from 1-M, which will print the Ith column of the local array
486 with M columns calculated by the compute.  See the discussion above
487 for how I can be specified with a wildcard asterisk to effectively
488 specify multiple values.
490 The {f_ID} and {f_ID\[I\]} attributes allow local vectors or arrays
491 calculated by a "fix"_fix.html to be output.  The ID in the attribute
492 should be replaced by the actual ID of the fix that has been defined
493 previously in the input script.
495 If {f_ID} is used as a attribute, then the local vector calculated by
496 the fix is printed.  If {f_ID\[I\]} is used, then I must be in the
497 range from 1-M, which will print the Ith column of the local with M
498 columns calculated by the fix.  See the discussion above for how I can
499 be specified with a wildcard asterisk to effectively specify multiple
500 values.
502 Here is an example of how to dump bond info for a system, including
503 the distance and energy of each bond:
505 compute 1 all property/local batom1 batom2 btype
506 compute 2 all bond/local dist eng
507 dump 1 all local 1000 tmp.dump index c_1\[1\] c_1\[2\] c_1\[3\] c_2\[1\] c_2\[2\] :pre
509 :line
511 This section explains the atom attributes that can be specified as
512 part of the {custom} and {cfg} styles.
514 The {id}, {mol}, {proc}, {procp1}, {type}, {element}, {mass}, {vx},
515 {vy}, {vz}, {fx}, {fy}, {fz}, {q} attributes are self-explanatory.
517 {Id} is the atom ID.  {Mol} is the molecule ID, included in the data
518 file for molecular systems.  {Proc} is the ID of the processor (0 to
519 Nprocs-1) that currently owns the atom.  {Procp1} is the proc ID+1,
520 which can be convenient in place of a {type} attribute (1 to Ntypes)
521 for coloring atoms in a visualization program.  {Type} is the atom
522 type (1 to Ntypes).  {Element} is typically the chemical name of an
523 element, which you must assign to each type via the "dump_modify
524 element"_dump_modify.html command.  More generally, it can be any
525 string you wish to associated with an atom type.  {Mass} is the atom
526 mass.  {Vx}, {vy}, {vz}, {fx}, {fy}, {fz}, and {q} are components of
527 atom velocity and force and atomic charge.
529 There are several options for outputting atom coordinates.  The {x},
530 {y}, {z} attributes write atom coordinates "unscaled", in the
531 appropriate distance "units"_units.html (Angstroms, sigma, etc).  Use
532 {xs}, {ys}, {zs} if you want the coordinates "scaled" to the box size,
533 so that each value is 0.0 to 1.0.  If the simulation box is triclinic
534 (tilted), then all atom coords will still be between 0.0 and 1.0.
535 I.e. actual unscaled (x,y,z) = xs*A + ys*B + zs*C, where (A,B,C) are
536 the non-orthogonal vectors of the simulation box edges, as discussed
537 in "Section 6.12"_Section_howto.html#howto_12.
539 Use {xu}, {yu}, {zu} if you want the coordinates "unwrapped" by the
540 image flags for each atom.  Unwrapped means that if the atom has
541 passed thru a periodic boundary one or more times, the value is
542 printed for what the coordinate would be if it had not been wrapped
543 back into the periodic box.  Note that using {xu}, {yu}, {zu} means
544 that the coordinate values may be far outside the box bounds printed
545 with the snapshot.  Using {xsu}, {ysu}, {zsu} is similar to using
546 {xu}, {yu}, {zu}, except that the unwrapped coordinates are scaled by
547 the box size. Atoms that have passed through a periodic boundary will
548 have the corresponding cooordinate increased or decreased by 1.0.
550 The image flags can be printed directly using the {ix}, {iy}, {iz}
551 attributes.  For periodic dimensions, they specify which image of the
552 simulation box the atom is considered to be in.  An image of 0 means
553 it is inside the box as defined.  A value of 2 means add 2 box lengths
554 to get the true value.  A value of -1 means subtract 1 box length to
555 get the true value.  LAMMPS updates these flags as atoms cross
556 periodic boundaries during the simulation.
558 The {mux}, {muy}, {muz} attributes are specific to dipolar systems
559 defined with an atom style of {dipole}.  They give the orientation of
560 the atom's point dipole moment.  The {mu} attribute gives the
561 magnitude of the atom's dipole moment.
563 The {radius} and {diameter} attributes are specific to spherical
564 particles that have a finite size, such as those defined with an atom
565 style of {sphere}.
567 The {omegax}, {omegay}, and {omegaz} attributes are specific to
568 finite-size spherical particles that have an angular velocity.  Only
569 certain atom styles, such as {sphere} define this quantity.
571 The {angmomx}, {angmomy}, and {angmomz} attributes are specific to
572 finite-size aspherical particles that have an angular momentum.  Only
573 the {ellipsoid} atom style defines this quantity.
575 The {tqx}, {tqy}, {tqz} attributes are for finite-size particles that
576 can sustain a rotational torque due to interactions with other
577 particles.
579 The {c_ID} and {c_ID\[I\]} attributes allow per-atom vectors or arrays
580 calculated by a "compute"_compute.html to be output.  The ID in the
581 attribute should be replaced by the actual ID of the compute that has
582 been defined previously in the input script.  See the
583 "compute"_compute.html command for details.  There are computes for
584 calculating the per-atom energy, stress, centro-symmetry parameter,
585 and coordination number of individual atoms.
587 Note that computes which calculate global or local quantities, as
588 opposed to per-atom quantities, cannot be output in a dump custom
589 command.  Instead, global quantities can be output by the
590 "thermo_style custom"_thermo_style.html command, and local quantities
591 can be output by the dump local command.
593 If {c_ID} is used as a attribute, then the per-atom vector calculated
594 by the compute is printed.  If {c_ID\[I\]} is used, then I must be in
595 the range from 1-M, which will print the Ith column of the per-atom
596 array with M columns calculated by the compute.  See the discussion
597 above for how I can be specified with a wildcard asterisk to
598 effectively specify multiple values.
600 The {f_ID} and {f_ID\[I\]} attributes allow vector or array per-atom
601 quantities calculated by a "fix"_fix.html to be output.  The ID in the
602 attribute should be replaced by the actual ID of the fix that has been
603 defined previously in the input script.  The "fix
604 ave/atom"_fix_ave_atom.html command is one that calculates per-atom
605 quantities.  Since it can time-average per-atom quantities produced by
606 any "compute"_compute.html, "fix"_fix.html, or atom-style
607 "variable"_variable.html, this allows those time-averaged results to
608 be written to a dump file.
610 If {f_ID} is used as a attribute, then the per-atom vector calculated
611 by the fix is printed.  If {f_ID\[I\]} is used, then I must be in the
612 range from 1-M, which will print the Ith column of the per-atom array
613 with M columns calculated by the fix.  See the discussion above for
614 how I can be specified with a wildcard asterisk to effectively specify
615 multiple values.
617 The {v_name} attribute allows per-atom vectors calculated by a
618 "variable"_variable.html to be output.  The name in the attribute
619 should be replaced by the actual name of the variable that has been
620 defined previously in the input script.  Only an atom-style variable
621 can be referenced, since it is the only style that generates per-atom
622 values.  Variables of style {atom} can reference individual atom
623 attributes, per-atom atom attributes, thermodynamic keywords, or
624 invoke other computes, fixes, or variables when they are evaluated, so
625 this is a very general means of creating quantities to output to a
626 dump file.
628 The {d_name} and {i_name} attributes allow to output custom per atom
629 floating point or integer properties that are managed by
630 "fix property/atom"_fix_property_atom.html.
632 See "Section 10"_Section_modify.html of the manual for information
633 on how to add new compute and fix styles to LAMMPS to calculate
634 per-atom quantities which could then be output into dump files.
636 :line
638 [Restrictions:]
640 To write gzipped dump files, you must either compile LAMMPS with the
641 -DLAMMPS_GZIP option or use the styles from the COMPRESS package
642 - see the "Making LAMMPS"_Section_start.html#start_2 section of
643 the documentation.
645 The {atom/gz}, {cfg/gz}, {custom/gz}, and {xyz/gz} styles are part
646 of the COMPRESS package.  They are only enabled if LAMMPS was built
647 with that package.  See the "Making
648 LAMMPS"_Section_start.html#start_3 section for more info.
650 The {atom/mpiio}, {cfg/mpiio}, {custom/mpiio}, and {xyz/mpiio} styles
651 are part of the MPIIO package.  They are only enabled if LAMMPS was
652 built with that package.  See the "Making
653 LAMMPS"_Section_start.html#start_3 section for more info.
655 The {xtc} style is part of the MISC package.  It is only enabled if
656 LAMMPS was built with that package.  See the "Making
657 LAMMPS"_Section_start.html#start_3 section for more info.  This is
658 because some machines may not support the low-level XDR data format
659 that XTC files are written with, which will result in a compile-time
660 error when a low-level include file is not found.  Putting this style
661 in a package makes it easy to exclude from a LAMMPS build for those
662 machines.  However, the MISC package also includes two compatibility
663 header files and associated functions, which should be a suitable
664 substitute on machines that do not have the appropriate native header
665 files.  This option can be invoked at build time by adding
666 -DLAMMPS_XDR to the CCFLAGS variable in the appropriate low-level
667 Makefile, e.g. src/MAKE/Makefile.foo.  This compatibility mode has
668 been tested successfully on Cray XT3/XT4/XT5 and IBM BlueGene/L
669 machines and should also work on IBM BG/P, and Windows XP/Vista/7
670 machines.
672 [Related commands:]
674 "dump h5md"_dump_h5md.html, "dump image"_dump_image.html,
675 "dump molfile"_dump_molfile.html, "dump_modify"_dump_modify.html,
676 "undump"_undump.html
678 [Default:]
680 The defaults for the {image} and {movie} styles are listed on the
681 "dump image"_dump_image.html doc page.