From 7c21f7a15879901497002569b9a8a5366c00c9af Mon Sep 17 00:00:00 2001
From: sjplimp <sjplimp@f3b2605a-c512-4ea7-a41b-209d697bcdaa>
Date: Tue, 28 Aug 2012 15:27:10 +0000
Subject: [PATCH] git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@8728
 f3b2605a-c512-4ea7-a41b-209d697bcdaa

---
 doc/group.html    | 47 ++++++++++++++++++++++++++++++++++++++++++++-
 doc/group.txt     | 49 +++++++++++++++++++++++++++++++++++++++++++++--
 doc/variable.html | 21 ++++++++++----------
 doc/variable.txt  | 21 ++++++++++----------
 4 files changed, 115 insertions(+), 23 deletions(-)

diff --git a/doc/group.html b/doc/group.html
index e771f17852..98f68e29a4 100644
--- a/doc/group.html
+++ b/doc/group.html
@@ -17,7 +17,7 @@
 </PRE>
 <UL><LI>ID = user-defined name of the group 
 
-<LI>style = <I>delete</I> or <I>region</I> or <I>type</I> or <I>id</I> or <I>molecule</I> or <I>subtract</I> or         <I>union</I> or <I>intersect</I> 
+<LI>style = <I>delete</I> or <I>region</I> or <I>type</I> or <I>id</I> or <I>molecule</I> or <I>variable</I> or       <I>subtract</I> or <I>union</I> or <I>intersect</I> 
 
 <PRE>  <I>delete</I> = no args
   <I>region</I> args = region-ID
@@ -30,6 +30,7 @@
       logical = "<>"
       value1,value2 = atom types or atom IDs or molecule IDs
       	(depending on <I>style</I>)
+  <I>variable</I> args  = variable-ID
   <I>subtract</I> args = two or more group IDs
   <I>union</I> args = one or more group IDs
   <I>intersect</I> args = two or more group IDs 
@@ -42,6 +43,7 @@
 group water type 3 4
 group sub id <= 150
 group polyA molecule <> 50 250
+group hienergy variable eng
 group boundary subtract all a2 a3
 group boundary union lower upper
 group boundary intersect upper flow
@@ -83,6 +85,49 @@ example above adds all atoms with IDs from 1 to 150 to the group named
 example above adds all atoms belonging to molecules with IDs from 50
 to 250 (inclusive) to the group named polyA.
 </P>
+<P>The <I>variable</I> style evaluates a variable to determine which atoms to
+add to the group.  It must be an <A HREF = "variable.html">atom-style variable</A>
+previously defined in the input script.  If the variable evaluates
+to a non-zero value for a particular atom, then that atom is added
+to the specified group.
+</P>
+<P>Atom-style variables can specify formulas that include thermodynamic
+quantities, per-atom values such as atom coordinates, or per-atom
+quantities calculated by computes, fixes, or other variables.  They
+can also include Boolean logic where 2 numeric values are compared to
+yield a 1 or 0 (effectively a true or false).  Thus using the
+<I>variable</I> style, is a general way to flag specific atoms to include
+or exclude from a group.
+</P>
+<P>For example, these lines define a variable "eatom" that calculates the
+potential energy of each atom and includes it in the group if its
+potential energy is above the threshhold value -3.0.
+</P>
+<PRE>compute         1 all pe/atom
+compute         2 all reduce sum c_1
+thermo_style    custom step temp pe c_2
+run             0 
+</PRE>
+<PRE>variable        eatom atom "c_1 > -3.0"
+group           hienergy variable eatom 
+</PRE>
+<P>Note that these lines
+</P>
+<PRE>compute         2 all reduce sum c_1
+thermo_style    custom step temp pe c_2
+run             0 
+</PRE>
+<P>are necessary to insure that the "eatom" variable is current when the
+group command invokes it.  Because the eatom variable computes the
+per-atom energy via the pe/atom compute, it will only be current if a
+run has been performed which evaluated pairwise energies, and the
+pe/atom compute was actually invoked during the run.  Printing the
+thermodyanmic info for compute 2 insures that this is the case, since
+it sums the pe/atom compute values (in the reduce compute) to output
+them to the screen.  See the "Variable Accuracy" section of the
+<A HREF = "variable.html">variable</A> doc page for more details on insuring that
+variables are current when they are evaluated between runs.
+</P>
 <P>The <I>subtract</I> style takes a list of two or more existing group names
 as arguments.  All atoms that belong to the 1st group, but not to any
 of the other groups are added to the specified group.
diff --git a/doc/group.txt b/doc/group.txt
index 53f52ffd86..638340fd16 100644
--- a/doc/group.txt
+++ b/doc/group.txt
@@ -13,8 +13,8 @@ group command :h3
 group ID style args :pre
 
 ID = user-defined name of the group :ulb,l
-style = {delete} or {region} or {type} or {id} or {molecule} or {subtract} or \
-        {union} or {intersect} :l
+style = {delete} or {region} or {type} or {id} or {molecule} or {variable} or \
+      {subtract} or {union} or {intersect} :l
   {delete} = no args
   {region} args = region-ID
   {type} or {id} or {molecule}
@@ -26,6 +26,7 @@ style = {delete} or {region} or {type} or {id} or {molecule} or {subtract} or \
       logical = "<>"
       value1,value2 = atom types or atom IDs or molecule IDs
       	(depending on {style})
+  {variable} args  = variable-ID
   {subtract} args = two or more group IDs
   {union} args = one or more group IDs
   {intersect} args = two or more group IDs :pre
@@ -37,6 +38,7 @@ group edge region regstrip
 group water type 3 4
 group sub id <= 150
 group polyA molecule <> 50 250
+group hienergy variable eng
 group boundary subtract all a2 a3
 group boundary union lower upper
 group boundary intersect upper flow
@@ -78,6 +80,49 @@ example above adds all atoms with IDs from 1 to 150 to the group named
 example above adds all atoms belonging to molecules with IDs from 50
 to 250 (inclusive) to the group named polyA.
 
+The {variable} style evaluates a variable to determine which atoms to
+add to the group.  It must be an "atom-style variable"_variable.html
+previously defined in the input script.  If the variable evaluates
+to a non-zero value for a particular atom, then that atom is added
+to the specified group.
+
+Atom-style variables can specify formulas that include thermodynamic
+quantities, per-atom values such as atom coordinates, or per-atom
+quantities calculated by computes, fixes, or other variables.  They
+can also include Boolean logic where 2 numeric values are compared to
+yield a 1 or 0 (effectively a true or false).  Thus using the
+{variable} style, is a general way to flag specific atoms to include
+or exclude from a group.
+
+For example, these lines define a variable "eatom" that calculates the
+potential energy of each atom and includes it in the group if its
+potential energy is above the threshhold value -3.0.
+
+compute         1 all pe/atom
+compute         2 all reduce sum c_1
+thermo_style    custom step temp pe c_2
+run             0 :pre
+
+variable        eatom atom "c_1 > -3.0"
+group           hienergy variable eatom :pre
+
+Note that these lines
+
+compute         2 all reduce sum c_1
+thermo_style    custom step temp pe c_2
+run             0 :pre
+
+are necessary to insure that the "eatom" variable is current when the
+group command invokes it.  Because the eatom variable computes the
+per-atom energy via the pe/atom compute, it will only be current if a
+run has been performed which evaluated pairwise energies, and the
+pe/atom compute was actually invoked during the run.  Printing the
+thermodyanmic info for compute 2 insures that this is the case, since
+it sums the pe/atom compute values (in the reduce compute) to output
+them to the screen.  See the "Variable Accuracy" section of the
+"variable"_variable.html doc page for more details on insuring that
+variables are current when they are evaluated between runs.
+
 The {subtract} style takes a list of two or more existing group names
 as arguments.  All atoms that belong to the 1st group, but not to any
 of the other groups are added to the specified group.
diff --git a/doc/variable.html b/doc/variable.html
index 217d500011..7051914f05 100644
--- a/doc/variable.html
+++ b/doc/variable.html
@@ -762,13 +762,14 @@ references to a compute or fix, and these values were calculated on
 the last timestep of a preceeding run, then they will be accessed and
 used by the variable and the result will be accurate.
 </P>
-<P>(2) LAMMPS may not be able to evaluate the variable and generate an
-error.  For example, if the variable requires a quantity from a
-<A HREF = "compute.html">compute</A> that is not current, LAMMPS will generate an
-error.  This means, for example, that such a variable cannot be
-evaluated before the first run has occurred.  Likewise, in between
-runs, such a variable cannot be accessed unless it was evaluated on
-the last timestep of the preceding run, e.g. by thermodynamic output.
+<P>(2) LAMMPS may not be able to evaluate the variable and will generate
+an error message stating so.  For example, if the variable requires a
+quantity from a <A HREF = "compute.html">compute</A> that is not current, LAMMPS
+will generate an error.  This means, for example, that such a variable
+cannot be evaluated before the first run has occurred.  Likewise, in
+between runs, such a variable cannot be accessed unless it was
+evaluated on the last timestep of the preceding run, e.g. by
+thermodynamic output.
 </P>
 <P>One way to get around this problem is to perform a 0-timestep run
 before using the variable.  For example, these commands
@@ -811,9 +812,9 @@ until a run is performed.  Thus if a variable attempts to print this
 value before the first run, zeroes will be output.  Again, performing
 a 0-timestep run before printing the variable has the desired effect.
 </P>
-<P>(3) The variable may be evaluated incorrectly.  And LAMMPS may have
-no way to detect this has occurred.  Consider the following sequence
-of commands:
+<P>(3) The variable may be evaluated incorrectly and LAMMPS may have no
+way to detect this has occurred.  Consider the following sequence of
+commands:
 </P>
 <PRE>pair_coeff 1 1 1.0 1.0
 run 1000
diff --git a/doc/variable.txt b/doc/variable.txt
index 2276232759..4c8267b002 100644
--- a/doc/variable.txt
+++ b/doc/variable.txt
@@ -756,13 +756,14 @@ references to a compute or fix, and these values were calculated on
 the last timestep of a preceeding run, then they will be accessed and
 used by the variable and the result will be accurate.
 
-(2) LAMMPS may not be able to evaluate the variable and generate an
-error.  For example, if the variable requires a quantity from a
-"compute"_compute.html that is not current, LAMMPS will generate an
-error.  This means, for example, that such a variable cannot be
-evaluated before the first run has occurred.  Likewise, in between
-runs, such a variable cannot be accessed unless it was evaluated on
-the last timestep of the preceding run, e.g. by thermodynamic output.
+(2) LAMMPS may not be able to evaluate the variable and will generate
+an error message stating so.  For example, if the variable requires a
+quantity from a "compute"_compute.html that is not current, LAMMPS
+will generate an error.  This means, for example, that such a variable
+cannot be evaluated before the first run has occurred.  Likewise, in
+between runs, such a variable cannot be accessed unless it was
+evaluated on the last timestep of the preceding run, e.g. by
+thermodynamic output.
 
 One way to get around this problem is to perform a 0-timestep run
 before using the variable.  For example, these commands
@@ -805,9 +806,9 @@ until a run is performed.  Thus if a variable attempts to print this
 value before the first run, zeroes will be output.  Again, performing
 a 0-timestep run before printing the variable has the desired effect.
 
-(3) The variable may be evaluated incorrectly.  And LAMMPS may have
-no way to detect this has occurred.  Consider the following sequence
-of commands:
+(3) The variable may be evaluated incorrectly and LAMMPS may have no
+way to detect this has occurred.  Consider the following sequence of
+commands:
 
 pair_coeff 1 1 1.0 1.0
 run 1000