calculate voronoi_decomposition

Syntax

calculate voronoi_decomposition keyword arg ...

• zero or more keyword/value pairs may be appended

• keyword = id or particle_group or use_meshes or write_every_time or file or area_cap_factor or volume_cap_factor or face_area_threshold

id value = command-ID
   command-ID = user-assigned name for the command call
particle_group = group-id
  group-id = group of particles for which average is evaluated
use_meshes arg = yes or no
write_every_time arg = write_every
  write_every = write Voronoi cells to pvtm file this every timesteps (must be used with file)
file arg = outfile_base
  outfile_base = filename base for the pvtm file (must be combined with write_every_time)
area_cap_factor arg = area_cap_factor
  area_cap_factor = factor to cap face areas
volume_cap_factor arg = volume_cap_factor
  volume_cap_factor = factor to cap cell volumes
face_area_threshold arg = minarea
  minarea = minimum area for a face to be counted

Examples

calculate voronoi_decomposition id myVoronoi
calculate voronoi_decomposition id voro_with_output write_every_time 1e-4 file post/voro
calculate voronoi_decomposition id clipped_voro area_cap_factor 1.3
calculate voronoi_decomposition id voro_mesh use_meshes yes

Description

Define a computation that calculates the radius weighted Voronoi tessellation of the particles in the simulation box. The tessellation is calculated using all atoms in the simulation, but non-zero values are only stored for atoms in the group.

The face_area_threshold keyword allows the suppression of faces below a given minimum area. Ultra small faces can occur as artifacts of the Voronoi tessellation.

The volume_cap_factor keyword allows to set a maximum volume for a Voronoi cell. Each Voronoi cell is initialized to a cube with edge length 2*maxrad*volume_cap_factor, where maxrad is the maximum particle radius in the simulation. The default value for volume_cap_factor is 3.

The maximum values are computed relative to the particle crosssection and volume, respectively. Larger cells/faces will be stored with the maximum values obtained by volume_cap_factor*v_part and area_cap_factor*r_part^2*pi.

The use_meshes keyword enables cutting of Voronoi cells by mesh elements. If set to yes, the Voronoi cells of particles close to mesh elements are cut off by a plane defined by the closest point on the mesh element and the contact normal. This ensures that no Voronoi cell extends over a mesh element, but might reduce in too small cells around nonconvex edges in the mesh. A fix wall/gran needs to be defined for this feature to work, and all meshes defined in this command are used to cut the Voronoi cells.

The Voronoi properties computed by this command can be written by adding them to the particle_properties of output_settings, see the output section below (recommended). It is also possible to write separate .pvtm files, which can be achieved by using the write_every_time and file keywords. The former sets the output interval, and the latter the base of the output file(s). Both keywords need to be set to write data; if one is omitted, calculate voronoi_decomposition will exit with an error message. A setting ‘file foo/bar’ will result in several files being written per timestep: one controller file foo/bar_%timestep.pvtm and one actual data file foo/bar_%timestep_%proc.vtm per processor. To visualize the data, load the .pvtm files in ParaView. The data file contains the cell id (identical to the corresponding particle id), cell volume, cell surface, number of faces and number of neighbors. The latter two are not necessarily equal: if a cell is cut off by either the domain boundary or a mesh element, a face is created, but no neighbor cell exists. Thus, if number of faces < number of neighbors, the cell might be a surface cell.

---

The Voronoi calculation is performed by the freely available Voro++ package, written by Chris Rycroft at UC Berkeley and LBL.

Note

The calculation of Voronoi volumes is performed by each processor for the atoms it owns, and includes the effect of ghost atoms stored by the processor. This assumes that the Voronoi cells of owned atoms are not affected by atoms beyond the ghost atom cut-off distance. This is usually a good assumption for dense systems, but may lead to underestimation of Voronoi volumes in low density systems. By default, the set of ghost atoms stored by each processor is determined by the cutoff used for pair_style interactions. The cutoff can be set explicitly via the comm_modify command (undocumented, please contact DCS if you need more information on this). The Voronoi cells for atoms adjacent to empty regions will extend into those regions up to the communication cutoff in x, y, or z. In that situation, an exterior face is created at the cutoff distance normal to the x, y, or z direction. For triclinic systems, the exterior face is parallel to the corresponding reciprocal lattice vector.

Output info:

The results of this calculation are internally stored in multiple fix property/atom. These can be accessed conveniently via dot access to the command ID used to created the calculate voronoi_decomposition command (id_commandID.property_name). It is also possible to access each fix property/atom directly via their own internal command IDs. See the table below for a complete overview of the available Voronoi properties and how to access them.

Voronoi property	property_name (dot access)	direct access	data type
volume per cell	volume	id_voronoi_volume_	scalar
total surface area per cell	total_area	id_voronoi_totalarea_	scalar
number of faces per cell	num_faces -or- number_of_faces	id_voronoi_numfaces_	scalar
number of neighbors per cell	num_neigh -or- number_of_neighbors	id_voronoi_num_neigh_	scalar
face areas per cell	area	id_voronoi_area_	vector

The difference between number_of_neighbors and number_of_faces is that the latter is the number of faces a cell has with another particle. So, their difference can be used eg. to detect surfaces. All these Voronoi properties contain a scalar (which can be added to the particle_properties list specified in the output_settings command), except area (this property stores a vector with individual face areas per cell).

Restrictions

It also requires you have a copy of the Voro++ library built and installed on your system. See instructions on obtaining and installing the Voro++ software in the src/VORONOI/README file.

Related commands

Default: use_meshes = no, volume_cap_factor = 3

top