.. index:: dump custom/vtk dump custom/vtk command ======================= Syntax """""" .. parsed-literal:: dump ID group-ID style N file args * ID = user-assigned name for the dump * group-ID = ID of the group of atoms to be dumped * style = *custom/vtk* * N = dump every this many timesteps * file = name of file to write dump info to * args = list of arguments for a particular style .. parsed-literal:: *custom/vtk* args = list of atom attributes possible attributes = id, mol, id_multisphere, type, element, mass, density, rho, p 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 .. parsed-literal:: id = atom ID mol = molecule ID id_multisphere = ID of multisphere body type = atom type element = name of atom element, as defined by :doc:`dump_modify ` 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[N] = Nth column of per-atom array calculated by a compute with ID f_ID = per-atom vector calculated by a fix with ID f_ID[N] = Nth column of per-atom array calculated by a fix with ID v_name = per-atom vector calculated by an atom-style variable with name shapex, shapey, shapez = semi-axes for superquadric particles blockiness1, blockiness2 = blockiness parameters for superquadric particles quat1, quat2, quat3, quat4 = quaternion components for superquadric paricles Examples """""""" .. parsed-literal:: dump dmpvtk all custom/vtk 100 dump*.myforce.vtu id type vx fx dump dmpvtp flow custom/vtk 100 dump*.displace.pvtp id type c_myD[1] c_myD[2] c_myD[3] v_ke Description """"""""""" Dump a snapshot of atom quantities to one or more files every N timesteps. The timesteps on which dump output is written can also be controlled by a variable; see the :doc:`dump_modify every ` command for details. Only information for atoms in the specified group is dumped. The :doc:`dump_modify thresh and region ` commands can also alter what atoms are included; see details below. As described below, the special character "*" and the suffix in the filename determine the kind of output. .. warning:: 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. .. warning:: Unless the :doc:`dump_modify sort ` option is invoked, the lines of atom information written to dump files will be in an indeterminate order for each snapshot. This is even true when running on a single processor, if the :doc:`atom_modify sort ` 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 *custom/vtk* style, sorting is off by default. See the :doc:`dump_modify ` doc page for details. ---------- The dimensions of the simulation box are written to a separate file for each snapshot (either in legacy VTK or XML format depending on the format of the main dump file) with the suffix *_boundingBox* appended to the given dump filename. For an orthogonal simulation box this information is saved as a rectilinear grid (legacy .vtk or .vtr XML format). Triclinic simulation boxes (non-orthogonal) are saved as hexahedrons in either legacy .vtk or .vtu XML format. Style *custom/vtk* allows you to specify a list of atom attributes to be written to the dump file for each atom. Possible attributes are listed above. In contrast to the *custom* style, the attributes are rearranged to ensure correct ordering of vector components (except for computes and fixes - these have to be given in the right order) and duplicate entries are removed. 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/vtk attributes is given below. Since position data is required to write VTK files "x y z" do not have to be specified explicitly. The VTK format uses a single snapshot of the system per file, thus a wildcard "*" must be included in the filename, as discussed below. Otherwise the dump files will get overwritten with the new snapshot each time. ---------- 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 :doc:`dump_modify first ` 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 :doc:`dump_modify every ` command. The :doc:`dump_modify every ` 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 :doc:`dump_modify first ` command is used. 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*.vtk becomes tmp.dump0.vtk, tmp.dump10000.vtk, tmp.dump20000.vtk, etc. Note that the :doc:`dump_modify pad ` 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. To write the output file in parallel the filename must end with either ".pvtu" or ".pvtp". If we assume that the filename is "data.pvtu" then one file with exactly this name is written. This contains the link to the processor data which is written in "data_X.vtu" files, where X (= 0,...,P-1) is the ID of the processor that wrote the file. Thus, in order to visualize all the data in ParaView one would open the "data.pvtu" file. Writing output in a parallel fashion can be particularly important on distributed HPC clusters and can significantly reduce runtime. .. note:: The legacy ".vtk" file type does not support parallel writing. 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 :doc:`dump_modify ` 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 "*" character and parallel file types together can produce a large number of small dump files! If *dump_modify binary* is used, the dump file(s) is/are 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. Additionally, *dump_modify compressor* can be used to specify the writing of compressed binary data. Options for compressors include: .. parsed-literal:: none: No compression zlib: Zlib compression lz4: Lz4 compression (VTK >= 8.0 required) ---------- This section explains the atom attributes that can be specified as part of the *custom/vtk* style. The *id*, *mol*, *id_multisphere*, *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. *id_multisphere* is the ID of the multisphere body that the particle belongs to (if your version supports multisphere). *type* is the atom type. *element* is typically the chemical name of an element, which you must assign to each type via the :doc:`dump_modify element ` command. More generally, it can be any string you wish to associate 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 are used to write atom coordinates "unscaled", in the appropriate distance :doc:`units ` (Angstroms, sigma, etc). Additionaly, you can use *xs*, *ys*, *zs* if you want to also save 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. 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 through a periodic boundary one or more times, the value is printed for what the coordinate would be if it had not been wrapped back into the periodic box. Note that using *xu*, *yu*, *zu* means 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 cooordinate 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. LIGGGHTS(R)-PUBLIC 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*. For *superquadric* particles these attributes give bounding sphere radius. 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[N]* attributes allow per-atom vectors or arrays calculated by a :doc:`compute ` 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 :doc:`compute ` 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/vtk command. Instead, global quantities can be output by the :doc:`thermo_style custom ` command, and local quantities can be output by the dump local command. If *c_ID* is used as an attribute, then the per-atom vector 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 column of the M-length per-atom array calculated by the compute. The *f_ID* and *f_ID[N]* attributes allow vector or array per-atom quantities calculated by a :doc:`fix ` 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 :doc:`fix ave/atom ` command is one that calculates per-atom quantities. Since it can time-average per-atom quantities produced by any :doc:`compute `, :doc:`fix `, or atom-style :doc:`variable `, 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[N]* is used, then N must be in the range from 1-M, which will print the Nth column of the M-length per-atom array calculated by the fix. The *v_name* attribute allows per-atom vectors calculated by a :doc:`variable ` 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 *shapex, shapey, shapez, blockiness1, blockiness2, quat1, quat2, quat3, quat4* attributes are available only for *superquadric* particles and hence require this :doc:`atom_style ` See :doc:`Section_modify ` of the manual for information on how to add new compute and fix styles to LIGGGHTS(R)-PUBLIC to calculate per-atom quantities which could then be output into dump files. ---------- Restrictions """""""""""" The *custom/vtk* style does not support writing of gzipped dump files. To be able to use *custom/vtk*, you have to link to the VTK library, please adapt your Makefile accordingly. You must compile LIGGGHTS(R)-PUBLIC with the -DLAMMPS_VTK option - see the :ref:`Making LIGGGHTS(R)-PUBLIC ` section of the documentation. The *custom/vtk* dump style neither supports buffering nor custom format strings. Related commands """""""""""""""" :doc:`dump `, :doc:`dump image `, :doc:`dump_modify `, :doc:`undump ` Default """"""" By default, files are written in ASCII format. If the file extension is not one of .vtk, .vtp or .vtu, the legacy VTK file format is used. .. _liws: http://www.cfdem.com .. _ld: Manual.html .. _lc: Section_commands.html#comm