From be2bcdd9f3f0359cb855c205de0fa663b49065ca Mon Sep 17 00:00:00 2001 From: sjplimp Date: Fri, 15 Feb 2008 19:09:18 +0000 Subject: [PATCH] git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@1516 f3b2605a-c512-4ea7-a41b-209d697bcdaa --- doc/atom_modify.html | 33 ++++++++++++++++++++++++++++----- doc/atom_modify.txt | 33 ++++++++++++++++++++++++++++----- doc/communicate.html | 11 +++++++---- doc/communicate.txt | 11 +++++++---- doc/neigh_modify.html | 12 +++++++----- doc/neigh_modify.txt | 12 +++++++----- 6 files changed, 84 insertions(+), 28 deletions(-) diff --git a/doc/atom_modify.html b/doc/atom_modify.html index b577d19854..b7d611bd5a 100644 --- a/doc/atom_modify.html +++ b/doc/atom_modify.html @@ -17,15 +17,17 @@

Examples:

-
atom_modify map hash 
+
atom_modify map hash
+atom_modify first colloid 
 

 
Description:
 

@@ -43,6 +45,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 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 and communicate group
+commands are two examples of commands that require this setting to
+work efficiently.  Several fixes, most notably time
+integration fixes like fix nve, 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
@@ -52,7 +74,8 @@ processors running the simulation.
 

 
Default:
 

-
By default, atomic (non-molecular) problems do not allocate maps.
-For molecular problems, the option default is map = array.
+
By default, atomic (non-molecular) problems do not allocate maps.  For
+molecular problems, the option default is map = array.  By default,
+first = all.
 

 
diff --git a/doc/atom_modify.txt b/doc/atom_modify.txt
index 85b311c755..31597f5e48 100644
--- a/doc/atom_modify.txt
+++ b/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
-  {map} value = {array} or {hash} :pre
+keyword = {map} or {first} :l
+  {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.
-For molecular problems, the option default is map = array.
+By default, atomic (non-molecular) problems do not allocate maps.  For
+molecular problems, the option default is map = array.  By default,
+first = all.
diff --git a/doc/communicate.html b/doc/communicate.html
index a46431ab43..7f2e977954 100644
--- a/doc/communicate.html
+++ b/doc/communicate.html
@@ -34,7 +34,8 @@ communicate multi group solvent
 

 
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
@@ -50,9 +51,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
-are needed for some kinds of particles.  The particles not in the
-specified group will still migrate to new processors as they move.
+group.  This can be useful for models where no ghost atoms are needed
+for some kinds of particles.  All atoms (not just those in the
+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
 

diff --git a/doc/communicate.txt b/doc/communicate.txt
index b54ee02acf..8ec1bee85a 100644
--- a/doc/communicate.txt
+++ b/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
-are needed for some kinds of particles.  The particles not in the
-specified group will still migrate to new processors as they move.
+group.  This can be useful for models where no ghost atoms are needed
+for some kinds of particles.  All atoms (not just those in the
+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
 
diff --git a/doc/neigh_modify.html b/doc/neigh_modify.html
index 272e88e545..0fdcc1fd57 100644
--- a/doc/neigh_modify.html
+++ b/doc/neigh_modify.html
@@ -72,6 +72,13 @@ some atom has moved more than half the skin distance (specified in the
 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:
@@ -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 fix
 rigid command for more details. 
 
-
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
diff --git a/doc/neigh_modify.txt b/doc/neigh_modify.txt
index 46f5ad81bb..e9a7efb451 100644
--- a/doc/neigh_modify.txt
+++ b/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