"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)

:line

compute voronoi/atom command :h3

[Syntax:]

compute ID group-ID voronoi/atom keyword arg ... :pre

ID, group-ID are documented in "compute"_compute.html command :ulb,l
voronoi/atom = style name of this compute command :l
zero or more keyword/value pairs may be appended :l
keyword = {only_group} or {surface} or {radius} or {edge_histo} or {edge_threshold} or {face_threshold} :l
  {only_group} = no arg
  {occupation} = no arg
  {surface} arg = sgroup-ID
    sgroup-ID = compute the dividing surface between group-ID and sgroup-ID
      this keyword adds a third column to the compute output
  {radius} arg = v_r
    v_r = radius atom style variable for a poly-disperse Voronoi tessellation
  {edge_histo} arg = maxedge
    maxedge = maximum number of Voronoi cell edges to be accounted in the histogram 
  {edge_threshold} arg = minlength
    minlength = minimum length for an edge to be counted
  {face_threshold} arg = minarea
    minarea = minimum area for a face to be counted :pre
:ule

[Examples:]

compute 1 all voronoi/atom
compute 2 precipitate voronoi/atom surface matrix
compute 3b precipitate voronoi/atom radius v_r 
compute 4 solute voronoi/atom only_group :pre
compute 5 defects voronoi/atom occupation :pre

[Description:]

Define a computation that calculates the Voronoi tessellation of the
atoms 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.

By default two quantities per atom are calculated by this compute.
The first is the volume of the Voronoi cell around each atom.  Any
point in an atom's Voronoi cell is closer to that atom than any other.
The second is the number of faces of the Voronoi cell, which is also
the number of nearest neighbors of the atom in the middle of the cell.

:line

If the {only_group} keyword is specified the tessellation is performed
only with respect to the atoms contained in the compute group. This is
equivalent to deleting all atoms not contained in the group prior to
evaluating the tessellation.

If the {surface} keyword is specified a third quantity per atom is
computed: the Voronoi cell surface of the given atom. {surface} takes
a group ID as an argument. If a group other than {all} is specified,
only the Voronoi cell facets facing a neighbor atom from the specified
group are counted towards the surface area.

In the example above, a precipitate embedded in a matrix, only atoms
at the surface of the precipitate will have non-zero surface area, and
only the outward facing facets of the Voronoi cells are counted (the
hull of the precipitate). The total surface area of the precipitate
can be obtained by running a "reduce sum" compute on c_2\[3\]

If the {radius} keyword is specified with an atom style variable as
the argument, a poly-disperse Voronoi tessellation is
performed. Examples for radius variables are

variable r1 atom (type==1)*0.1+(type==2)*0.4
compute radius all property/atom radius
variable r2 atom c_radius :pre

Here v_r1 specifies a per-type radius of 0.1 units for type 1 atoms
and 0.4 units for type 2 atoms, and v_r2 accesses the radius property
present in atom_style sphere for granular models.

The {edge_histo} keyword activates the compilation of a histogram of
number of edges on the faces of the Voronoi cells in the compute
group. The argument maxedge of the this keyword is the largest number
of edges on a single Voronoi cell face expected to occur in the
sample. This keyword adds the generation of a global vector with
maxedge+1 entries. The last entry in the vector contains the number of
faces with with more than maxedge edges. Since the polygon with the
smallest amount of edges is a triangle, entries 1 and 2 of the vector
will always be zero.

The {edge_threshold} and {face_threshold} keywords allow the
suppression of edges below a given minimum length and faces below a
given minimum area. Ultra short edges and ultra small faces can occur
as artifacts of the Voronoi tessellation. These keywords will affect
the neighbor count and edge histogram outputs.

If the {occupation} keyword is specified the tessellation is only
performed for the first invocation of the compute and then stored.
For all following invocations of the compute the number of atoms in
each Voronoi cell in the stored tessellation is counted. In this mode
the compute returns a per-atom array with 2 columns. The first column
is the number of atoms currently in the Voronoi volume defined by this 
atom at the time of the first invocation of the compute (note that the 
atom may have moved significantly). The second column contains the
total number of atoms sharing the Voronoi cell of the stored 
tessellation at the location of the current atom. Numbers in column one
can be any positive integer including zero, while column two values will 
always be greater than zero. Column one data can be used to locate 
vacancies (the coordinates are given by the atom coordinates at the 
time step when the compute was first invoked), while column two data
can be used to identify interstitial atoms.

:line

The Voronoi calculation is performed by the freely available "Voro++
package"_voronoi, written by Chris Rycroft at UC Berkeley and LBL,
which must be installed on your system when building LAMMPS for use
with this compute.  See instructions on obtaining and installing the
Voro++ software in the src/VORONOI/README file.

:link(voronoi,http://math.lbl.gov/voro++)

IMPORTANT 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 liquid and solid
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"_pair_style.html interactions.  The cutoff can be set
explicitly via the "communicate cutoff"_communicate.html command.

IMPORTANT NOTE: The Voro++ package performs its calculation in 3d.
This should still work for a 2d LAMMPS simulation, to effectively
compute Voronoi "areas", so long as the z-dimension of the box is
roughly the same (or smaller) compared to the separation of the atoms.
Typical values for the z box dimensions in a 2d LAMMPS model are -0.5
to 0.5, which satisfies the criterion for most "units"_units.html
systems.  Note that you define the z extent of the simulation box for
2d simulations when using the "create_box"_create_box.html or
"read_data"_read_data.html commands.

[Output info:]

This compute calculates a per-atom array with 2 columns. In regular
dynamic tessellation mode the first column is the Voronoi volume, the 
second is the neighbor count, as described above (read above for the 
output data in case the {occupation} keyword is specified). 
These values can be accessed by any command that
uses per-atom values from a compute as input.  See "Section_howto
15"_Section_howto.html#howto_15 for an overview of LAMMPS output
options.

The Voronoi cell volume will be in distance "units"_units.html cubed.

[Restrictions:]

This compute is part of the VORONOI package.  It is only enabled if
LAMMPS was built with that package.  See the "Making
LAMMPS"_Section_start.html#start_3 section for more info.

[Related commands:]

"dump custom"_dump.html

[Default:] none