doc/src/compute_voronoi_atom.txt

   1 "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
   2
   3 :link(lws,http://lammps.sandia.gov)
   4 :link(ld,Manual.html)
   5 :link(lc,Section_commands.html#comm)
   6
   7 :line
   8
   9 compute voronoi/atom command :h3
  10
  11 [Syntax:]
  12
  13 compute ID group-ID voronoi/atom keyword arg ... :pre
  14
  15 ID, group-ID are documented in "compute"_compute.html command :ulb,l
  16 voronoi/atom = style name of this compute command :l
  17 zero or more keyword/value pairs may be appended :l
  18 keyword = {only_group} or {surface} or {radius} or {edge_histo} or {edge_threshold}
  19 or {face_threshold} or {neighbors} or {peratom} :l
  20   {only_group} = no arg
  21   {occupation} = no arg
  22   {surface} arg = sgroup-ID
  23     sgroup-ID = compute the dividing surface between group-ID and sgroup-ID
  24       this keyword adds a third column to the compute output
  25   {radius} arg = v_r
  26     v_r = radius atom style variable for a poly-disperse Voronoi tessellation
  27   {edge_histo} arg = maxedge
  28     maxedge = maximum number of Voronoi cell edges to be accounted in the histogram
  29   {edge_threshold} arg = minlength
  30     minlength = minimum length for an edge to be counted
  31   {face_threshold} arg = minarea
  32     minarea = minimum area for a face to be counted
  33   {neighbors} value = {yes} or {no} = store list of all neighbors or no
  34   {peratom} value = {yes} or {no} = per-atom quantities accessible or no :pre
  35 :ule
  36
  37 [Examples:]
  38
  39 compute 1 all voronoi/atom
  40 compute 2 precipitate voronoi/atom surface matrix
  41 compute 3b precipitate voronoi/atom radius v_r
  42 compute 4 solute voronoi/atom only_group
  43 compute 5 defects voronoi/atom occupation
  44 compute 6 all voronoi/atom neighbors yes :pre
  45
  46 [Description:]
  47
  48 Define a computation that calculates the Voronoi tessellation of the
  49 atoms in the simulation box.  The tessellation is calculated using all
  50 atoms in the simulation, but non-zero values are only stored for atoms
  51 in the group.
  52
  53 By default two per-atom quantities are calculated by this compute.
  54 The first is the volume of the Voronoi cell around each atom.  Any
  55 point in an atom's Voronoi cell is closer to that atom than any other.
  56 The second is the number of faces of the Voronoi cell. This is
  57 equal to the number of nearest neighbors of the central atom,
  58 plus any exterior faces (see note below). If the {peratom} keyword
  59 is set to "no", the per-atom quantities are still calculated,
  60 but they are not accessible.
  61
  62 :line
  63
  64 If the {only_group} keyword is specified the tessellation is performed
  65 only with respect to the atoms contained in the compute group. This is
  66 equivalent to deleting all atoms not contained in the group prior to
  67 evaluating the tessellation.
  68
  69 If the {surface} keyword is specified a third quantity per atom is
  70 computed: the Voronoi cell surface of the given atom. {surface} takes
  71 a group ID as an argument. If a group other than {all} is specified,
  72 only the Voronoi cell facets facing a neighbor atom from the specified
  73 group are counted towards the surface area.
  74
  75 In the example above, a precipitate embedded in a matrix, only atoms
  76 at the surface of the precipitate will have non-zero surface area, and
  77 only the outward facing facets of the Voronoi cells are counted (the
  78 hull of the precipitate). The total surface area of the precipitate
  79 can be obtained by running a "reduce sum" compute on c_2\[3\]
  80
  81 If the {radius} keyword is specified with an atom style variable as
  82 the argument, a poly-disperse Voronoi tessellation is
  83 performed. Examples for radius variables are
  84
  85 variable r1 atom (type==1)*0.1+(type==2)*0.4
  86 compute radius all property/atom radius
  87 variable r2 atom c_radius :pre
  88
  89 Here v_r1 specifies a per-type radius of 0.1 units for type 1 atoms
  90 and 0.4 units for type 2 atoms, and v_r2 accesses the radius property
  91 present in atom_style sphere for granular models.
  92
  93 The {edge_histo} keyword activates the compilation of a histogram of
  94 number of edges on the faces of the Voronoi cells in the compute
  95 group. The argument {maxedge} of the this keyword is the largest number
  96 of edges on a single Voronoi cell face expected to occur in the
  97 sample. This keyword adds the generation of a global vector with
  98 {maxedge}+1 entries. The last entry in the vector contains the number of
  99 faces with with more than {maxedge} edges. Since the polygon with the
 100 smallest amount of edges is a triangle, entries 1 and 2 of the vector
 101 will always be zero.
 102
 103 The {edge_threshold} and {face_threshold} keywords allow the
 104 suppression of edges below a given minimum length and faces below a
 105 given minimum area. Ultra short edges and ultra small faces can occur
 106 as artifacts of the Voronoi tessellation. These keywords will affect
 107 the neighbor count and edge histogram outputs.
 108
 109 If the {occupation} keyword is specified the tessellation is only
 110 performed for the first invocation of the compute and then stored.
 111 For all following invocations of the compute the number of atoms in
 112 each Voronoi cell in the stored tessellation is counted. In this mode
 113 the compute returns a per-atom array with 2 columns. The first column
 114 is the number of atoms currently in the Voronoi volume defined by this
 115 atom at the time of the first invocation of the compute (note that the
 116 atom may have moved significantly). The second column contains the
 117 total number of atoms sharing the Voronoi cell of the stored
 118 tessellation at the location of the current atom. Numbers in column
 119 one can be any positive integer including zero, while column two
 120 values will always be greater than zero. Column one data can be used
 121 to locate vacancies (the coordinates are given by the atom coordinates
 122 at the time step when the compute was first invoked), while column two
 123 data can be used to identify interstitial atoms.
 124
 125 If the {neighbors} value is set to yes, then
 126 this compute creates a local array with 3 columns. There
 127 is one row for each face of each Voronoi cell. The
 128 3 columns are the atom ID of the atom that owns the cell,
 129 the atom ID of the atom in the neighboring cell
 130 (or zero if the face is external), and the area of the face.
 131 The array can be accessed by any command that
 132 uses local values from a compute as input.  See "this
 133 section"_Section_howto.html#howto_15 for an overview of LAMMPS output
 134 options. More specifically, the array can be accessed by a
 135 "dump local"_dump.html command to write a file containing
 136 all the Voronoi neighbors in a system:
 137
 138 compute 6 all voronoi/atom neighbors yes
 139 dump d2 all local 1 dump.neighbors index c_6\[1\] c_6\[2\] c_6\[3\] :pre
 140
 141 If the {face_threshold} keyword is used, then only faces
 142 with areas greater than the threshold are stored.
 143
 144 :line
 145
 146 The Voronoi calculation is performed by the freely available "Voro++
 147 package"_voronoi, written by Chris Rycroft at UC Berkeley and LBL,
 148 which must be installed on your system when building LAMMPS for use
 149 with this compute.  See instructions on obtaining and installing the
 150 Voro++ software in the src/VORONOI/README file.
 151
 152 :link(voronoi,http://math.lbl.gov/voro++/)
 153
 154 NOTE: The calculation of Voronoi volumes is performed by each
 155 processor for the atoms it owns, and includes the effect of ghost
 156 atoms stored by the processor.  This assumes that the Voronoi cells of
 157 owned atoms are not affected by atoms beyond the ghost atom cut-off
 158 distance.  This is usually a good assumption for liquid and solid
 159 systems, but may lead to underestimation of Voronoi volumes in low
 160 density systems.  By default, the set of ghost atoms stored by each
 161 processor is determined by the cutoff used for
 162 "pair_style"_pair_style.html interactions.  The cutoff can be set
 163 explicitly via the "comm_modify cutoff"_comm_modify.html command.  The
 164 Voronoi cells for atoms adjacent to empty regions will extend into
 165 those regions up to the communication cutoff in x, y, or z.  In that
 166 situation, an exterior face is created at the cutoff distance normal
 167 to the x, y, or z direction.  For triclinic systems, the exterior face
 168 is parallel to the corresponding reciprocal lattice vector.
 169
 170 NOTE: The Voro++ package performs its calculation in 3d.  This will
 171 still work for a 2d LAMMPS simulation, provided all the atoms have the
 172 same z coordinate. The Voronoi cell of each atom will be a columnar
 173 polyhedron with constant cross-sectional area along the z direction
 174 and two exterior faces at the top and bottom of the simulation box. If
 175 the atoms do not all have the same z coordinate, then the columnar
 176 cells will be accordingly distorted. The cross-sectional area of each
 177 Voronoi cell can be obtained by dividing its volume by the z extent of
 178 the simulation box.  Note that you define the z extent of the
 179 simulation box for 2d simulations when using the
 180 "create_box"_create_box.html or "read_data"_read_data.html commands.
 181
 182 [Output info:]
 183
 184 By default, this compute calculates a per-atom array with 2
 185 columns. In regular dynamic tessellation mode the first column is the
 186 Voronoi volume, the second is the neighbor count, as described above
 187 (read above for the output data in case the {occupation} keyword is
 188 specified).  These values can be accessed by any command that uses
 189 per-atom values from a compute as input.  See "Section
 190 6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output
 191 options. If the {peratom} keyword is set to "no", the per-atom array
 192 is still created, but it is not accessible.
 193
 194 If the {edge_histo} keyword is used, then this compute generates a
 195 global vector of length {maxedge}+1, containing a histogram of the
 196 number of edges per face.
 197
 198 If the {neighbors} value is set to yes, then this compute calculates a
 199 local array with 3 columns. There is one row for each face of each
 200 Voronoi cell.
 201
 202 NOTE: Some LAMMPS commands such as the "compute
 203 reduce"_compute_reduce.html command can accept either a per-atom or
 204 local quantity. If this compute produces both quantities, the command
 205 may access the per-atom quantity, even if you want to access the local
 206 quantity.  This effect can be eliminated by using the {peratom}
 207 keyword to turn off the production of the per-atom quantities.  For
 208 the default value {yes} both quantities are produced.  For the value
 209 {no}, only the local array is produced.
 210
 211 The Voronoi cell volume will be in distance "units"_units.html cubed.
 212 The Voronoi face area will be in distance "units"_units.html squared.
 213
 214 [Restrictions:]
 215
 216 This compute is part of the VORONOI package.  It is only enabled if
 217 LAMMPS was built with that package.  See the "Making
 218 LAMMPS"_Section_start.html#start_3 section for more info.
 219
 220 [Related commands:]
 221
 222 "dump custom"_dump.html, "dump local"_dump.html
 223
 224 [Default:] {neighbors} no, {peratom} yes