git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@10393 f3b2605a-c512-4ea7-a41b-209d697bcdaa

doc/compute_voronoi_atom.html

@@ -13,33 +13,103 @@
 </H3>
 <P><B>Syntax:</B>
 </P>
-<PRE>compute ID group-ID voronoi/atom 
+<PRE>compute ID group-ID voronoi/atom keyword arg 
 </PRE>
-<UL><LI>ID, group-ID are documented in <A HREF = "compute.html">compute</A> command
+<UL><LI>ID, group-ID are documented in <A HREF = "compute.html">compute</A> command 
+
 <LI>voronoi/atom = style name of this compute command 
+
+<LI>keyword = <I>only_group</I> or <I>surface</I> or <I>radius</I> or <I>edge_histo</I> or <I>edge_threshold</I> or <I>face_threshold</I> 
+
+<PRE>  <I>only_group</I> = no args
+  <I>surface</I> 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
+  <I>radius</I> arg = v_r
+    v_r = radius atom style variable for a poly-disperse voronoi tessellation
+  <I>edge_histo</I> arg = maxedge
+    maxedge = maximum number of voronoi cell edges to be accounted in the histogram 
+  <I>edge_threshold</I> arg = minlength
+    minlength = minimum length for an edge to be counted
+  <I>face_threshold</I> arg = minarea
+    minarea = minimum area for a face to be counted 
+</PRE>
+
 </UL>
 <P><B>Examples:</B>
 </P>
-<PRE>compute 1 all voronoi/atom 
+<PRE>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>
 <P><B>Description:</B>
 </P>
-<P>Define a computation that calculates the Voronoi tesselation of the
-atoms in the simulation box.  The tesselation is calculated using
-all atoms in the simulation, but non-zero values are only stored
-for atoms in the group.
+<P>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.
 </P>
-<P>Two quantites 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.
+<P>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.
 </P>
+<HR>
+
+<P>If the <I>only_group</I> 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.
+</P>
+<P>If the <I>surface</I> keyword is specified a third quantity per atom is
+computed: the voronoi cell surface of the given atom. <I>surface</I> takes
+a group ID as an argument. If a group other than <I>all</I> is specified,
+only the voronoi cell facets facing a neighbor atom from the specified
+group are counted towards the surface area.
+</P>
+<P>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]
+</P>
+<P>If the <I>radius</I> keyword is specified with an atom style variable as
+the argument, a poly-disperse voronoi tessellation is
+performed. Examples for radius variables are
+</P>
+<PRE>variable r1 atom (type==1)*0.1+(type==2)*0.4
+compute radius all property/atom radius
+variable r2 atom c_radius 
+</PRE>
+<P>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.
+</P>
+<P>The <I>edge_histo</I> 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.
+</P>
+<P>The <I>edge_threshold</I> and <I>face_threshold</I> 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.
+</P>
+<HR>
+
 <P>The Voronoi calculation is performed by the freely available <A HREF = "http://math.lbl.gov/voro++">Voro++
 package</A>, 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.
+with this compute.  See instructions on obtaining and installing the
+Voro++ software in the src/VORONOI/README file.
 </P>
 
 
@@ -56,7 +126,7 @@ explicitly via the <A HREF = "communicate.html">communicate cutoff</A> command.
 </P>
 <P>IMPORTANT NOTE: The Voro++ package performs its calculation in 3d.
 This should still work for a 2d LAMMPS simulation, to effectively
-compute Vornoi "areas", so long as the z-dimension of the box is
+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 <A HREF = "units.html">units</A>

doc/compute_voronoi_atom.txt

@@ -10,33 +10,99 @@ compute voronoi/atom command :h3
 
 [Syntax:]
 
-compute ID group-ID voronoi/atom :pre
-
-ID, group-ID are documented in "compute"_compute.html command
-voronoi/atom = style name of this compute command :ul
+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
+keyword = {only_group} or {surface} or {radius} or {edge_histo} or {edge_threshold} or {face_threshold} :l
+  {only_group} = no args
+  {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 :pre
+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
 
 [Description:]
 
-Define a computation that calculates the Voronoi tesselation of the
-atoms in the simulation box.  The tesselation is calculated using
-all atoms in the simulation, but non-zero values are only stored
-for atoms in the group.
+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.
 
-Two quantites 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
 
 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.
+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++)
 
@@ -53,7 +119,7 @@ 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 Vornoi "areas", so long as the z-dimension of the box is
+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