"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 [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 {bond} or {dcd} or {xtc} or {xyz} or {custom} :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 {bond} args = none {dcd} args = none {xtc} args = none {xyz} args = none {custom} args = list of atom attributes possible attributes = tag, mol, type, x, y, z, xs, ys, zs, xu, yu, zu, ix, iy, iz, vx, vy, vz, fx, fy, fz, q, mux, muy, muz, quatw, quati, quatj, quatk, tqx, tqy, tqz, c_ID, c_ID\[N\], f_ID, f_ID\[N\], v_name tag = atom ID mol = molecule ID type = atom type x,y,z = unscaled atom coordinates xs,ys,zs = scaled atom coordinates xu,yu,zu = 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 dipolar atom quatw,quati,quatj,quatk = quaternion components for aspherical particles tqx,tqy,tqz = torque on aspherical particles c_ID = per-atom scalar value calculated by a compute with ID c_ID\[N\] = Nth component of per-atom vector calculated by a compute with ID f_ID = per-atom scalar value calculated by a fix with ID f_ID\[N\] = Nth component of per-atom vector calculated by a fix with ID v_name = per-atom value calculated by an atom-style variable with name :pre :ule [Examples:] dump myDump all atom 100 dump.atom dump 2 subgroup atom 50 dump.run.bin dump 4a all custom 100 dump.myforce.* tag type x y vx fx dump 4b flow custom 100 dump.%.myforce tag type c_myF\[3\] v_ke 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. 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 one per processor). Only information for atoms in the specified group is dumped. The "dump_modify"_dump_modify.html command can also alter what atoms are included. Not all styles support all these options; see details below. IMPORTANT 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. When LAMMPS is running in parallel, the atom information written to dump files (typically one line per atom) may be written in an indeterminate order. This is because data for a single snapshot is collected from multiple processors. This is always the case for the {atom}, {bond}, and {custom} styles. It is also the case for the {xyz} style if the dump group is not {all}. It is not the case for the {dcd} and {xtc} styles which always write atoms in sorted order. So does the {xyz} style if the dump group is {all}. :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}, {bond}, 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.cs.sandia.gov/~sjplimp/pizza.html, work with this format. 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. For style {bond}, the bond topology between atoms is written, in the same format specified in data files read in by the "read_data"_read_data.html command. Both atoms in the bond must be in the dump group for the bond to be written. Any bonds that have been broken (see the "bond_style"_bond_style.html command) by setting their bond type to 0 are not written. Bonds that have been turned off (see the "fix shake"_fix_shake.html or "delete_bonds"_delete_bonds.html commands) by setting their bond type negative are written into the file. 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 dump custom quantities is given below. 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 dump group must be {all} for 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 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 {xtc} style writes XTC files, a compressed trajectory format used by the GROMACS molecular dynamics package, and described "here"_http://www.gromacs.org/documentation/reference_3.3/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 dump group must be {all} for 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. Note that DCD, XTC, and XYZ formatted files can be read directly by "VMD"_http://www.ks.uiuc.edu/Research/vmd (a popular molecular viewing program). We are told VMD will also read LAMMPS {atom} style dump files since someone has added a LAMMPS format plug-in to VMD. It may require an initial snapshot from an XYZ formatted file to get started. :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. N can be changed between runs by using the "dump_modify"_dump_modify.html command (not allowed for {dcd} style). 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 wild-card 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. If a "%" character appears in the filename, then one file is written for each processor 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. Note that the "*" and "%" characters can be used together to produce a large number of small dump files! 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 This section explains the atom quantities that can be specified as part of the {custom} style. The {tag}, {mol}, {type}, {x}, {y}, {z}, {vx}, {vy}, {vz}, {fx}, {fy}, {fz}, {q} keywords are self-explanatory. {Tag} is the atom ID. {Mol} is the molecule ID, included in the data file for molecular systems. The {x}, {y}, {z} keywords 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. 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 size printed with the snapshot. The image flags can be printed directly using the {ix}, {iy}, {iz} keywords. The "dump_modify"_dump_modify.html command describes in more detail what is meant by scaled vs unscaled coordinates and the image flags. The {mux}, {muy}, {muz} keywords are specific to dipolar systems defined with an atom style of {dipole}. They give the orientation of the atom's dipole. The {quatw}, {quati}, {quatj}, {quatk}, {tqx}, {tqy}, {tqz} keywords are specific to aspherical particles defined with an atom style of {ellipsoid}. The first 4 are the components of the quaternion that define the orientation of the particle. The final 3 give the rotational torque on the particle. The {c_ID} and {c_ID\[N\]} keywords allow scalar or vector per-atom quantities calculated by a "compute"_compute.html to be output. The ID in the keyword 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 per-atom computes for calculating the energy, stress, centro-symmetry parameter, and coordination number of individual atoms. Note that computes which calculate global scalar and vector quantities, as opposed to per-atom quantities, cannot be output in a dump. Instead, these quantities can be output by the "thermo_style custom"_thermo_style.html command. If {c_ID} is used as a keyword, then the scalar per-atom quantity calculated by the compute is printed. If {c_ID\[N\]} is used, then N must be in the range from 1-M, which will print the Nth component of the M-length per-atom vector calculated by the compute. The {f_ID} and {f_ID\[N\]} keywords allow scalar or vector per-atom quantities calculated by a "fix"_fix.html to be output. The ID in the keyword 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 keyword, then the scalar per-atom quantity calculated by the fix is printed. If {f_ID\[N\]} is used, then N must be in the range from 1-M, which will print the Nth component of the M-length per-atom vector calculated by the fix. The {v_name} keyword allows per-atom quantities calculated by a "variable"_variable.html to be output. The name in the keyword 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. See "this section"_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:] Scaled coordinates cannot be writted to dump files when the simulation box is triclinic (non-orthogonal). Note that this is the default for dump style {atom}; the "dump_modify command"_dump_modify.html must be used to change it. The exception is DCD files which store the tilt factors for subsequent visualization by programs like "VMD"_http://www.ks.uiuc.edu/Research/vmd. To write gzipped dump files, you must compile LAMMPS with the -DLAMMPS_GZIP option - see the "Making LAMMPS"_Section_start.html#2_2 section of the documentation. The {bond} style is part of the "molecular" package. It is only enabled if LAMMPS was built with that package. See the "Making LAMMPS"_Section_start.html#2_3 section for more info. The {xtc} style is part of the "xtc" package. It is only enabled if LAMMPS was built with that package. See the "Making LAMMPS"_Section_start.html#2_3 section for more info. This is because some machines may not support the lo-level XDR data format that XTC files are written with, which will result in a compile-time error when a lo-level include file is not found. Putting this style in a package makes it easy to exclude from a LAMMPS build for those machines. However, the XTC package also includes two compatibility header files and associated functions, which should be a suitable substitute on machines that do not have the appropriate native header files. This option can be invoked at build time by adding -DLAMMPS_XDR to the CCFLAGS variable in the appropriate lo-level Makefile, e.g. src/MAKE/Makefile.foo. This compatibility mode has been tested successfully on Cray XT3 and IBM BlueGene/L machines and should also work on the Cray XT4, IBM BG/P, and Windows XP machines. [Related commands:] "dump_modify"_dump_modify.html, "undump"_undump.html [Default:] none