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

doc/set.html

@@ -26,37 +26,51 @@
 	  <I>meso_e</I> or <I>meso_cv</I> or <I>meso_rho</I> 
 
 <PRE>  <I>type</I> value = atom type
+    value can be an atom-style variable (see below)
   <I>type/fraction</I> values = type fraction seed
     type = new atom type
     fraction = fraction of selected atoms to set to new atom type
     seed = random # seed (positive integer)
   <I>mol</I> value = molecule ID
+    value can be an atom-style variable (see below)
   <I>x</I>,<I>y</I>,<I>z</I> value = atom coordinate (distance units)
+    value can be an atom-style variable (see below)
   <I>charge</I> value = atomic charge (charge units)
+    value can be an atom-style variable (see below)
   <I>dipole</I> values = x y z
     x,y,z = orientation of dipole moment vector
+    any of x,y,z can be an atom-style variable (see below)
   <I>dipole/random</I> value = seed Dlen
     seed = random # seed (positive integer) for dipole moment orientations
     Dlen = magnitude of dipole moment (dipole units)
   <I>quat</I> values = a b c theta
     a,b,c = unit vector to rotate particle around via right-hand rule
     theta = rotation angle (degrees)
+    any of a,b,c,theta can be an atom-style variable (see below)
   <I>quat/random</I> value = seed
     seed = random # seed (positive integer) for quaternion orientations
   <I>diameter</I> value = diameter of spherical particle (distance units)
+    value can be an atom-style variable (see below)
   <I>shape</I> value = Sx Sy Sz
     Sx,Sy,Sz = 3 diameters of ellipsoid (distance units)
   <I>length</I> value = len
     len = length of line segment (distance units)
+    len can be an atom-style variable (see below)
   <I>tri</I> value = side
     side = side length of equilateral triangle (distance units)
+    side can be an atom-style variable (see below)
   <I>theta</I> value = angle (degrees)
     angle = orientation of line segment with respect to x-axis
+    angle can be an atom-style variable (see below)
   <I>angmom</I> values = Lx Ly Lz
     Lx,Ly,Lz = components of angular momentum vector (distance-mass-velocity units)
+    any of Lx,Ly,Lz can be an atom-style variable (see below)
   <I>mass</I> value = per-atom mass (mass units)
+    value can be an atom-style variable (see below)
   <I>density</I> value = particle density for sphere or ellipsoid (mass/distance^3 or mass/distance^2 or mass/distance units, depending on dimensionality of particle)
+    value can be an atom-style variable (see below)
   <I>volume</I> value = particle volume for Peridynamic particle (distance^3 units)
+    value can be an atom-style variable (see below)
   <I>image</I> nx ny nz
     nx,ny,nz = which periodic image of the simulation box the atom is in
   <I>bond</I> value = bond type for all bonds between selected atoms
@@ -64,8 +78,11 @@
   <I>dihedral</I> value = dihedral type for all dihedrals between selected atoms
   <I>improper</I> value = improper type for all impropers between selected atoms
   <I>meso_e</I> value = energy of SPH particles (need units)
+    value can be an atom-style variable (see below)
   <I>meso_cv</I> value = heat capacity of SPH particles (need units)
-  <I>meso_rho</I> value = density of SPH particles (need units) 
+    value can be an atom-style variable (see below)
+  <I>meso_rho</I> value = density of SPH particles (need units)
+    value can be an atom-style variable (see below) 
 </PRE>
 
 </UL>
@@ -91,24 +108,33 @@ for overriding the default values assigned by the
 be useful for altering pairwise and molecular force interactions,
 since force-field coefficients are defined in terms of types.  It can
 be used to change the labeling of atoms by atom type or molecule ID
-when they are output in <A HREF = "dump.html">dump</A> files.  It can be useful for
-debugging purposes; i.e. positioning an atom at a precise location to
-compute subsequent forces or energy.
+when they are output in <A HREF = "dump.html">dump</A> files.  It can also be useful
+for debugging purposes; i.e. positioning an atom at a precise location
+to compute subsequent forces or energy.
+</P>
+<P>Note that the <I>style</I> and <I>ID</I> arguments determine which atoms have
+their properties reset.  The remaining keywords specify which
+properties to reset and what the new values are.  Some strings like
+<I>type</I> or <I>mol</I> can be used as a style and/or a keyword.
+</P>
+<HR>
+
+<P>This section describes how to select which atoms to change
+the properties of, via the <I>style</I> and <I>ID</I> arguments.
 </P>
 <P>The style <I>atom</I> selects all the atoms in a range of atom IDs.  The
 style <I>type</I> selects all the atoms in a range of types.  The style
 <I>mol</I> selects all the atoms in a range of molecule IDs.
 </P>
-<P>In each of the range cases, a single value can be specified, or a
-wildcard asterisk can be used to specify a range of values.  This
-takes the form "*" or "*n" or "n*" or "m*n".  For example, for the
-style <I>type</I>, if N = the number of atom types, then an asterisk with
-no numeric values means all types from 1 to N.  A leading asterisk
-means all types from 1 to n (inclusive).  A trailing asterisk means
-all types from n to N (inclusive).  A middle asterisk means all types
-from m to n (inclusive).  Note that the loweest value for the wildcard
-is 1, not 0, so you cannot not use this form to select atoms
-with molecule ID = 0, for example.
+<P>In each of the range cases, the range can be specified as a single
+numeric value, or a wildcard asterisk can be used to specify a range
+of values.  This takes the form "*" or "*n" or "n*" or "m*n".  For
+example, for the style <I>type</I>, if N = the number of atom types, then
+an asterisk with no numeric values means all types from 1 to N.  A
+leading asterisk means all types from 1 to n (inclusive).  A trailing
+asterisk means all types from n to N (inclusive).  A middle asterisk
+means all types from m to n (inclusive).  For all the styles except
+<I>mol</I>, the lowest value for the wildcard is 1; for <I>mol</I> it is 0.
 </P>
 <P>The style <I>group</I> selects all the atoms in the specified group.  The
 style <I>region</I> selects all the atoms in the specified geometric
@@ -117,6 +143,33 @@ for details of how to specify a group or region.
 </P>
 <HR>
 
+<P>This section describes the keyword options for which properties to
+change, for the selected atoms.
+</P>
+<P>Note that except where explicitly prohibited below, all of the
+keywords allow an <A HREF = "variable.html">atom-style variable</A> to be used as
+the specified value(s).  If the value is a variable, it should be
+specified as v_name, where name is the variable name.  In this case,
+the variable will be evaluated, and its resulting per-atom value used
+to determine the value assigned to each selected atom.
+</P>
+<P>Atom-style variables can specify formulas with various mathematical
+functions, and include <A HREF = "thermo_style.html">thermo_style</A> command
+keywords for the simulation box parameters and timestep and elapsed
+time.  They can also include per-atom values, such as atom
+coordinates.  Thus it is easy to specify a time-dependent or
+spatially-dependent set of per-atom values.  As explained on the
+<A HREF = "variable.html">variable</A> doc page, atomfile-style variables can be
+used in place of atom-style variables, and thus as arguments to the
+set command.  Atomfile-style variables read their per-atoms values
+from a file.
+</P>
+<P>IMPORTANT NOTE: Atom-style and atomfile-style variables return
+floating point per-atom values.  If the values are assigned to an
+integer variable, such as the molecule ID, then the floating point
+value is truncated to its integer portion, e.g. a value of 2.6 would
+become 2.
+</P>
 <P>Keyword <I>type</I> sets the atom type for all selected atoms.  The
 specified value must be from 1 to ntypes, where ntypes was set by the
 <A HREF = "create_box.html">create_box</A> command or the <I>atom types</I> field in the
@@ -128,7 +181,7 @@ selected atoms.  The actual number of atoms changed is not guaranteed
 to be exactly the requested fraction, but should be statistically
 close.  Random numbers are used in such a way that a particular atom
 is changed or not changed, regardless of how many processors are being
-used.
+used.  This keyword does not allow use of an atom-style variable.
 </P>
 <P>Keyword <I>mol</I> sets the molecule ID for all selected atoms.  The <A HREF = "atom_style.html">atom
 style</A> being used must support the use of molecule
@@ -148,7 +201,8 @@ moment vectors of the selected atoms and sets the magnitude of each to
 the specified <I>Dlen</I> value.  For 2d systems, the z component of the
 orientation is set to 0.0.  Random numbers are used in such a way that
 the orientation of a particular atom is the same, regardless of how
-many processors are being used.
+many processors are being used.  This keyword does not allow use of an
+atom-style variable.
 </P>
 <P>Keyword <I>quat</I> uses the specified values to create a quaternion
 (4-vector) that represents the orientation of the selected atoms.  The
@@ -176,7 +230,8 @@ numbers are used in such a way that the orientation of a particular
 atom is the same, regardless of how many processors are being used.
 For 2d systems, only orientations in the xy plane are generated.  As
 with keyword <I>quat</I>, for ellipsoidal particles, the 3 shape values
-must be non-zero for each particle set by this command.
+must be non-zero for each particle set by this command.  This keyword
+does not allow use of an atom-style variable.
 </P>
 <P>Keyword <I>diameter</I> sets the size of the selected atoms.  The particles
 must be finite-size spheres as defined by the <A HREF = "atom_style.html">atom_style
@@ -265,7 +320,7 @@ the simulation.  The flags can be output with atom snapshots via the
 <A HREF = "dump.html">dump</A> command.  If a value of NULL is specified for any of
 nx,ny,nz, then the current image value for that dimension is
 unchanged.  For non-periodic dimensions only a value of 0 can be
-specified.
+specified.  This keyword does not allow use of atom-style variables.
 </P>
 <P>This command can be useful after a system has been equilibrated and
 atoms have diffused one or more box lengths in various directions.
@@ -287,7 +342,7 @@ atoms in a particular bond (angle, etc) must be selected atoms in
 order for the change to be made.  The value of nbondtype (nangletypes,
 etc) was set by the <I>bond types</I> (<I>angle types</I>, etc) field in the
 header of the data file read by the <A HREF = "read_data.html">read_data</A>
-command.
+command.  These keywords do not allow use of an atom-style variable.
 </P>
 <P>Keywords <I>meso_e</I>, <I>meso_cv</I>, and <I>meso_rho</I> set the energy, heat
 capacity, and density of smmothed particle hydrodynamics (SPH)