dump custom/vtm command
Purpose
Dumps particle data to VTM files for postprocessing/visualization
Syntax
dump ID group-ID style N file keyword value particle_properties particle_property_args meshes mesh_args mesh_properties mesh_property_args local_gran cpgl_id
ID = user-assigned name for the dump
group-ID = ID of the group of atoms to be dumped
style = custom/vtm
N = dump every this many timesteps
file = name of file to write dump info to
zero or more keyword/value pairs may be appended
keyword = required keyword
keyword = write_pvd_file
write_pvd_file value = yes or no
particle_properties optional keyword
particle_properties particle_property_args = args
args = list of attributes appended to the particle output
possible attributes = id, mol, multisphere_id, 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
id = atom ID
mol = molecule ID
multisphere_id = ID of multisphere body
type = atom type
element = name of atom element, as defined by 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
roundness1, roundness2 = roundness/blockiness parameters for superquadric particles
quat1, quat2, quat3, quat4 = quaternion components for superquadric or convex particles
quat = quaternion components for superquadric particles as a 4-element vector
meshes = optional keyword
meshes mesh_args = ids
ids = either keyword 'all' or a list of IDs of fix mesh/surface or fix wall/gran of type 'primitive'
mesh_properties = optional keyword (requires keyword ‘meshes’, must follow the mesh_args)
mesh_properties mesh_property_args = dump-identifier dump-identifier = 'stress' or 'id' or 'wear' or 'vel' or 'stresscomponents' or 'owner' or 'area' or 'aedges' or 'acorners' or 'nneigs'
local_gran = optional keyword
local_gran cpgl_id = id
id = ID of a compute pair/gran/local
Examples
dump dmpcat all custom/vtm 200 dump_results_*.vtm particle_properties id mass
dump dmpcat all custom/vtm 300 output_*.vtm meshes all mesh_properties id area
dump dmpcat all custom/vtm 400 post/dump_*.vtm meshes chute mesh_properties id stress local_gran cpgl
dump dmpcat all custom/vtm 500 dump_*.vtm write_pvd_file yes particle_properties v_var radius meshes plough
Description
This dump writes a vtm file that contains all data requested in the arguments of the dump. ParaView. An update of the data is made every N timesteps. The timesteps on which dump output is written can also be controlled by a variable; see the dump_modify every command for details. Only information for atoms in the specified group is dumped.
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.
The keyword scripts needs to be preceded by a appropriate ParaView Catalyst Python script. These scripts can be generated using the CatalystScriptGeneratorPlugin that is available in ParaView. For further details on this tool see the official ParaView website.
Dump custom/vtm allows you to specify a list of atom attributes, preceded by the keyword particle_properties to be written to the dump file for each atom. Possible attributes are listed above. 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/vtm attributes is given below. Since position data is required for vtk elements “x y z” do not have to be specified explicitly.
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.
The dump command accepts one optional keyword write_pvd_file whose arguments is either yes or no. If this keyword is set to yes a a pvd file will be written that contains all timesteps of a simulations listed in a single file that can be read (and updated) by ParaView.
This section explains the atom attributes that can be specified as part of the custom/vtm style.
The id, mol, multisphere_id, 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. multisphere_id 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 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 units (Angstroms, sigma, etc). Additionally, 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 coordinate 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. Aspherix® 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 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 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 status_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 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 fix ave/atom command is one that calculates per-atom quantities. Since it can time-average per-atom quantities produced by any compute, fix, or atom-style 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 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, roundness1, roundness2, quat1, quat2, quat3, quat4, quat attributes are available only for superquadric particles and hence require this particle shape. The quaternion (quat*) outputs are also available for convex particles. By default the output of quat1, quat2, quat3, and quat4 is suppressed and replaced by a single per-particle property TENSOR that can be used for the visual representation. If the output of the individual quaternion elements is nevertheless required the command dump_modify write_quat on/off enables this output.
The mesh/vtk style can be used to dump active mesh geometries defined via fix mesh/surface or primitive walls, defined via fix wall/gran commands. To do so the keyword meshes needs to be specified and followed either by the keyword ‘all’ or a list of fix mesh/surface ids or fix wall/gran commands. The keyword ‘all’ will automatically dump all such meshes and primitive walls.
Optionally, the keyword mesh_properties can be appended in order to stream mesh parameters to ParaView. In case several meshes are dumped not all might have all properties available and in this case a property will only be dumped for meshes that posses it. Different keywords can be appended to the mesh_properties keyword to dump the per-triangle averaged stress in normal and shear direction, id, velocity, wear, stress components (fx / element area, fy / element area, fz / element area), area (area of each element) or the process which owns the element (visualisation of the parallel decomposition). The group-ID is ignored. Keywords aedges and acorners dump the number of active edges/corners per face. Keyword nneighs dumps the number of face neighbors Aspherix® has recognized for each face.
If the keyword local_gran is specified the data of a compute pair/gran/local can be visualized. The argument cpgl_id is the ID of such a compute object. For further information see also the dump local/gran/vtk command.
Dump_modify:
This keyword can be influenced by several dump_modify options. Additionally it supports the remove_mesh keyword, followed by an id of a fix mesh/surface or a fix wall/gran with type ‘primitive’. This will remove a specific mesh or primitive wall from the output.
Example:
dump_modify my_dump_custom_vtm remove_mesh my_static_mesh
Default
By default no meshes are written and only particle and bounding box information is streamed to ParaView. The particles, by default, only provide their position data.