\(\renewcommand{\AA}{\text{Å}}\)

dump vtk command

Syntax

dump ID group-ID vtk N file args

  • ID = user-assigned name for the dump

  • group-ID = ID of the group of atoms to be dumped

  • vtk = style of dump command (other styles such as atom or cfg or dcd or xtc or xyz or local or custom are discussed on the dump doc page)

  • N = dump every this many timesteps

  • file = name of file to write dump info to

  • args = same as arguments for dump_style custom

Examples

dump dmpvtk all vtk 100 dump*.myforce.vtk id type vx fx
dump dmpvtp flow vtk 100 dump*.%.displace.vtp 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 in a format readable by the VTK visualization toolkit or other visualization tools that use it, such as ParaView. The time steps on which dump output is written can also be controlled by a variable; see the dump_modify every command for details.

This dump style is similar to dump_style custom but uses the VTK library to write data to VTK simple legacy or XML format, depending on the filename extension specified for the dump file. This can be either *.vtk for the legacy format or *.vtp and *.vtu, respectively, for XML format; see the VTK homepage for a detailed description of these formats. Since this naming convention conflicts with the way binary output is usually specified (see below), the dump_modify binary command allows setting of a binary option for this dump style explicitly.

Only information for atoms in the specified group is dumped. The dump_modify thresh and region commands can also alter what atoms are included; see details below.

As described below, special characters (”*”, “%”) 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 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 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 vtk style, sorting is off by default. See the dump_modify 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 vtk allows you to specify a list of atom attributes to be written to the dump file for each atom. The list of possible attributes is the same as for the dump_style custom command; see its documentation page for a listing and an explanation of each attribute.

Note

Since position data is required to write VTK files the atom attributes “x y z” do not have to be specified explicitly; they will be included in the dump file regardless. Also, in contrast to the custom style, the specified vtk 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.

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 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 dump_modify every command. The 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 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 dump_modify pad command can be used to ensure 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 preceded by an underscore character. For example, tmp.dump%.vtp becomes tmp.dump_0.vtp, tmp.dump_1.vtp, … tmp.dump_P-1.vtp, etc. This creates smaller files and can be a fast mode of output on parallel machines that support parallel I/O for output.

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 command. These options can be the most efficient way of writing out dump files when running on large numbers of processors.

For the legacy VTK format “%” is ignored and P = 1, i.e., only processor 0 does write files.

Note that using the “*” and “%” characters together can produce a large number of small dump files!

If dump_modify binary is used, 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.

Restrictions

The vtk style does not support writing of gzipped dump files.

The vtk dump style is part of the VTK package. It is only enabled if LAMMPS was built with that package. See the Build package page for more info.

To use this dump style, you also must link to the VTK library. See the info in lib/vtk/README and ensure the Makefile.lammps file in that directory is appropriate for your machine.

The vtk dump style supports neither buffering or custom format strings.

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.