dump field/vtk/cell command

Purpose

Dumps fix data of fixes using “region neighbor lists” to VTI files

Warning

GPU support for this command has not been tested and may not work as expected.

Syntax

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 = field/vtk/cell

  • N = dump every this many timesteps

  • file = name of file to write dump info to

  • args = list of arguments for a particular style

field/vtk/cell args = any ID of a fix using "region neighbor lists"

Examples

dump dmpfield all field/vtk/cell 100 dump*.euler.vti id-euler

Description

The field/vtk/cell style dumps the output of any fix command that uses internally a “region neighbor list” into a series of VTI files. The user has to provide the ID of this fix.

Fixes with a “region neighbor list” usually load and use some mesh-based data as flow fields, magnetic fields and so on. Other examples are fixes that map particle-based data on a regular mesh.

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 keyword 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.

Example post-processing

The vti files can be either visualized using ParaView or Ovito. Alternatively, Python can be used to parse the files using the vtk module if additional calculations need to be performed on the individual cells. Below is an example of reading such a vti file and a loop over all its cells. For each cell its centroid is computed and the count value stored on each cell is extracted as well and written to a file.

import vtk
inputFile = "post/myeuler_5000.vti"
outputFile = "count.csv"
reader = vtk.vtkXMLImageDataReader()
reader.SetFileName(inputFile)
reader.Update()
vti = reader.GetOutput()
ncells = vti.GetNumberOfCells()
cellData = vti.GetCellData()
count = cellData.GetArray("count")
out = open(outputFile, "w")
out.write("id, center_x, center_y, center_z, count\n")
for i in range(ncells):
    cell = vti.GetCell(i)
    bounds = cell.GetBounds()
    center = (0.5*(bounds[0]+bounds[1]), 0.5*(bounds[2]+bounds[3]), 0.5*(bounds[4]+bounds[5]))
    thisCount = count.GetValue(i)
    out.write(str(i) + ", " + str(center[0]) + ", " + str(center[1]) + ", " + str(center[2]) + ", " + str(thisCount) + "\n")
out.close()

The output file will start with a header line, followed by a list of all cells with information about their id, centroids and the value of their count array. Here is some example output:

id, center_x, center_y, center_z, count
0, -0.07500000000000001, -0.07500000000000001, 0.03, 89.39082355495877
1, -0.025, -0.07500000000000001, 0.03, 83.95381686942486
[...]

Default

By default, files are written in ASCII format.