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

doc/atom_modify.html

@@ -17,15 +17,17 @@
 </PRE>
 <UL><LI>one or more keyword/value pairs may be appended 
 
-<LI>keyword = <I>map</I> 
+<LI>keyword = <I>map</I> or <I>first</I> 
 
-<PRE>  <I>map</I> value = <I>array</I> or <I>hash</I> 
+<PRE>  <I>map</I> value = <I>array</I> or <I>hash</I>
+  <I>first</I> value = group-ID = group whose atoms will appear first in internal atom lists 
 </PRE>
 
 </UL>
 <P><B>Examples:</B>
 </P>
-<PRE>atom_modify map hash 
+<PRE>atom_modify map hash
+atom_modify first colloid 
 </PRE>
 <P><B>Description:</B>
 </P>
@@ -43,6 +45,26 @@ slightly slower than the <I>array</I> method, but its memory cost is
 proportional to N/P on each processor, where P is the total number of
 processors running the simulation.
 </P>
+<P>The <I>first</I> keyword allows a <A HREF = "group.html">group</A> to be specified whose
+atoms will be maintained as the first atoms in each processor's list
+of owned atoms.  This in only useful when the specified group is a
+small fraction of all the atoms, and there are other operations LAMMPS
+is performing that will be sped-up significantly by being able to loop
+over the smaller set of atoms.  Otherwise the reordering required by
+this option will be a net slow-down.  The <A HREF = "neigh_modify.html">neigh_modify
+include</A> and <A HREF = "communicate.html">communicate group</A>
+commands are two examples of commands that require this setting to
+work efficiently.  Several <A HREF = "fix.html">fixes</A>, most notably time
+integration fixes like <A HREF = "fix_nve.html">fix nve</A>, also take advantage of
+this setting if the group they operate on is the group specified by
+this command.
+</P>
+<P>Note that because the atom_modify command must be used in an input
+script before a simulation is setup and groups are defined, this means
+the <I>first</I> keyword will specify a group that is not yet defined.
+This is OK; LAMMPS will check that the group exists before the first
+simulation is performed.
+</P>
 <P><B>Restrictions:</B>
 </P>
 <P>This command must be used before the simulation box is defined by a
@@ -52,7 +74,8 @@ processors running the simulation.
 </P>
 <P><B>Default:</B>
 </P>
-<P>By default, atomic (non-molecular) problems do not allocate maps.
+<P>By default, atomic (non-molecular) problems do not allocate maps.  For
-For molecular problems, the option default is map = array.
+molecular problems, the option default is map = array.  By default,
+first = all.
 </P>
 </HTML>

doc/atom_modify.txt

@@ -13,13 +13,15 @@ atom_modify command :h3
 atom_modify keyword value ... :pre
 
 one or more keyword/value pairs may be appended :ulb,l
-keyword = {map} :l
+keyword = {map} or {first} :l
-  {map} value = {array} or {hash} :pre
+  {map} value = {array} or {hash}
+  {first} value = group-ID = group whose atoms will appear first in internal atom lists :pre
 :ule
 
 [Examples:]
 
-atom_modify map hash :pre
+atom_modify map hash
+atom_modify first colloid :pre
 
 [Description:]
 
@@ -37,6 +39,26 @@ slightly slower than the {array} method, but its memory cost is
 proportional to N/P on each processor, where P is the total number of
 processors running the simulation.
 
+The {first} keyword allows a "group"_group.html to be specified whose
+atoms will be maintained as the first atoms in each processor's list
+of owned atoms.  This in only useful when the specified group is a
+small fraction of all the atoms, and there are other operations LAMMPS
+is performing that will be sped-up significantly by being able to loop
+over the smaller set of atoms.  Otherwise the reordering required by
+this option will be a net slow-down.  The "neigh_modify
+include"_neigh_modify.html and "communicate group"_communicate.html
+commands are two examples of commands that require this setting to
+work efficiently.  Several "fixes"_fix.html, most notably time
+integration fixes like "fix nve"_fix_nve.html, also take advantage of
+this setting if the group they operate on is the group specified by
+this command.
+
+Note that because the atom_modify command must be used in an input
+script before a simulation is setup and groups are defined, this means
+the {first} keyword will specify a group that is not yet defined.
+This is OK; LAMMPS will check that the group exists before the first
+simulation is performed.
+
 [Restrictions:]
 
 This command must be used before the simulation box is defined by a
@@ -46,5 +68,6 @@ This command must be used before the simulation box is defined by a
 
 [Default:]
 
-By default, atomic (non-molecular) problems do not allocate maps.
+By default, atomic (non-molecular) problems do not allocate maps.  For
-For molecular problems, the option default is map = array.
+molecular problems, the option default is map = array.  By default,
+first = all.

doc/communicate.html

@@ -34,7 +34,8 @@ communicate multi group solvent
 </P>
 <P>This command sets the style of inter-processor communication that
 occurs each timestep as atom coordinates and other properties are
-exchanged between neighboring processors.
+exchanged between neighboring processors and stored as properties of
+ghost atoms.
 </P>
 <P>The default style is <I>single</I> which means each processor acquires
 information for ghost atoms that are within a single distance from its
@@ -50,9 +51,11 @@ neighbor list construction option that may also be beneficial for
 simulations of this kind.
 </P>
 <P>The <I>group</I> option will limit communication to atoms in the specified
-group.  This can be useful for certain models where no ghost copies
+group.  This can be useful for models where no ghost atoms are needed
-are needed for some kinds of particles.  The particles not in the
+for some kinds of particles.  All atoms (not just those in the
-specified group will still migrate to new processors as they move.
+specified group) will still migrate to new processors as they move.
+The group specified with this option must also be specified via the
+"atom_modify first" command.
 </P>
 <P><B>Restrictions:</B> none
 </P>

doc/communicate.txt

@@ -27,7 +27,8 @@ communicate multi group solvent :pre
 
 This command sets the style of inter-processor communication that
 occurs each timestep as atom coordinates and other properties are
-exchanged between neighboring processors.
+exchanged between neighboring processors and stored as properties of
+ghost atoms.
 
 The default style is {single} which means each processor acquires
 information for ghost atoms that are within a single distance from its
@@ -43,9 +44,11 @@ neighbor list construction option that may also be beneficial for
 simulations of this kind.
 
 The {group} option will limit communication to atoms in the specified
-group.  This can be useful for certain models where no ghost copies
+group.  This can be useful for models where no ghost atoms are needed
-are needed for some kinds of particles.  The particles not in the
+for some kinds of particles.  All atoms (not just those in the
-specified group will still migrate to new processors as they move.
+specified group) will still migrate to new processors as they move.
+The group specified with this option must also be specified via the
+"atom_modify first" command.
 
 [Restrictions:] none
 

doc/neigh_modify.html

@@ -72,6 +72,13 @@ some atom has moved more than half the skin distance (specified in the
 command), the <I>every</I> and <I>delay</I> parameters refer to the longest
 (outermost) timestep.
 </P>
+<P>The <I>include</I> option limits the building of pairwise neighbor lists to
+atoms in the specified group.  This can be useful for models where a
+large portion of the simulation is particles that do not interact with
+other particles or with each other via pairwise interactions.  The
+group specified with this option must also be specified via the
+"atom_modify first" command.
+</P>
 <P>The <I>exclude</I> option turns off pairwise interactions between certain
 pairs of atoms, by not including them in the neighbor list.  These are
 sample scenarios where this is useful:
@@ -88,11 +95,6 @@ to freeze a wall or portion of a bio-molecule.
 body can be turned off to save needless computation.  See the <A HREF = "fix_rigid.html">fix
 rigid</A> command for more details. 
 </UL>
-<P>The <I>include</I> option limits the building of pairwise neighbor lists to
-atoms in the specified group.  This can be useful if a large portion
-of the simulation is particles that do not interact with the remainder
-of the simulation or with each other via pairwise interactions.
-</P>
 <P>The <I>exclude type</I> option turns off the pairwise interaction if one
 atom is of type M and the other of type N.  M can equal N.  The
 <I>exclude group</I> option turns off the interaction if one atom is in the

doc/neigh_modify.txt

@@ -66,6 +66,13 @@ When the rRESPA integrator is used (see the "run_style"_run_style.html
 command), the {every} and {delay} parameters refer to the longest
 (outermost) timestep.
 
+The {include} option limits the building of pairwise neighbor lists to
+atoms in the specified group.  This can be useful for models where a
+large portion of the simulation is particles that do not interact with
+other particles or with each other via pairwise interactions.  The
+group specified with this option must also be specified via the
+"atom_modify first" command.
+
 The {exclude} option turns off pairwise interactions between certain
 pairs of atoms, by not including them in the neighbor list.  These are
 sample scenarios where this is useful:
@@ -82,11 +89,6 @@ When one or more rigid bodies are specified, interactions within each
 body can be turned off to save needless computation.  See the "fix
 rigid"_fix_rigid.html command for more details. :l,ule
 
-The {include} option limits the building of pairwise neighbor lists to
-atoms in the specified group.  This can be useful if a large portion
-of the simulation is particles that do not interact with the remainder
-of the simulation or with each other via pairwise interactions.
-
 The {exclude type} option turns off the pairwise interaction if one
 atom is of type M and the other of type N.  M can equal N.  The
 {exclude group} option turns off the interaction if one atom is in the