From e098b4386872306dd5626ac683bd974c642114f4 Mon Sep 17 00:00:00 2001 From: sjplimp Date: Wed, 13 Jan 2010 20:56:56 +0000 Subject: [PATCH] git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@3675 f3b2605a-c512-4ea7-a41b-209d697bcdaa --- doc/atom_modify.html | 73 +++++++++++++++++++++++++++++++++++++------- doc/atom_modify.txt | 73 +++++++++++++++++++++++++++++++++++++------- doc/variable.html | 4 +-- doc/variable.txt | 4 +-- 4 files changed, 128 insertions(+), 26 deletions(-) diff --git a/doc/atom_modify.html b/doc/atom_modify.html index 7d53300401..4ccf3c430f 100644 --- a/doc/atom_modify.html +++ b/doc/atom_modify.html @@ -13,20 +13,24 @@

Syntax:

-
atom_modify keyword value ... 
+
atom_modify keyword values ... 
 

 
 
Examples:
 

 
atom_modify map hash
+atom_modify map array sort 10000 2.0
 atom_modify first colloid 
 

 
Description:
@@ -59,16 +63,55 @@ integration fixes like fix nve, also take advantage
 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.
+
It is OK to use the first keyword with a group that has not yet been
+defined, e.g. to use the atom_modify command at the beginning of your
+input script.  LAMMPS will check that the group exists before the
+first simulation is performed.
+

+
The sort keyword turns on a spatial sorting or reordering of atoms
+within each processor's sub-domain every Nfreq timesteps.  This can
+improve cache performance and thus speed=up a LAMMPS simulation, as
+discussed in a paper by (Meloni).  In tests we have done,
+the amount of speed-up can range from zero to 3-4x.  It is typically
+more effective at speeding up simulations of liquids as opposed to
+solids.
+

+
Reordering is peformed every Nfreq timesteps during a dynamics run
+or iterations during a minimization.  More precisely, reordering
+occurs at the first reneighboring that occurs after the target
+timestep.  The reordering is performed locally by each processor,
+using bins of the specified binsize.  If binsize is set to 0.0,
+then a binsize equal to half the neighbor cutoff
+distance (force cutoff plus skin distance) is used, which is a
+reasonable value.  After the atoms have been binned, they are
+reordered so that atoms in the same bin are adjacent to each other in
+the processor's 1d list of atoms.
+

+
The goal of this procedure is for atoms be near each other in the
+processor's 1d list of atoms that are also near to each other
+spatially.  This can improve cache performance when pairwise
+intereractions and neighbor lists are computed.  Note that if bins are
+too small, there will be few atoms/bin.  Likewise if bins are too
+large, there will be many atoms/bin.  In both cases, the goal of cache
+locality can be undermined.
+

+
IMPORTANT NOTE: Running a simulation with sorting on versus off should
+not change the simulation results in a statistical sense.  However,
+reordering will induce round-off differences, which will lead to
+diverging trajectories when comparing two simluations.  Various
+commands, particularly those which use random numbers (e.g. velocity
+create, and fix langevin), may
+generate different results (but statistically identical) depending on
+the order in which they process atoms.  The order of atoms in a
+dump file will also change if sorting is enabled.
 

 
Restrictions:
 

-
This command must be used before the simulation box is defined by a
-read_data or create_box command.
+
The map keyword can only be used before the simulation box is defined
+by a read_data or create_box
+command.
+

+
The first and sort options cannot be used together.
 

 
Related commands: none
 

@@ -76,6 +119,14 @@ simulation is performed.
 

 
By default, atomic (non-molecular) problems do not allocate maps.  For
 molecular problems, the option default is map = array.  By default, a
-"first" group is not defined.
+"first" group is not defined.  By default, sorting is enabled with a
+frequency of 1000 and a binsize of 0.0, which means the neighbor
+cutoff will be used to set the bin size.
+

+

+
+
+
+
(Meloni) Meloni and Rasati, J Chem Phys, 126, 121102 (2007).
 

 
diff --git a/doc/atom_modify.txt b/doc/atom_modify.txt
index 46d5e9599c..0ed5436f80 100644
--- a/doc/atom_modify.txt
+++ b/doc/atom_modify.txt
@@ -10,17 +10,21 @@ atom_modify command :h3
 
 [Syntax:]
 
-atom_modify keyword value ... :pre
+atom_modify keyword values ... :pre
 
 one or more keyword/value pairs may be appended :ulb,l
-keyword = {map} or {first} :l
+keyword = {map} or {first} or {sort} :l
   {map} value = {array} or {hash}
-  {first} value = group-ID = group whose atoms will appear first in internal atom lists :pre
+  {first} value = group-ID = group whose atoms will appear first in internal atom lists
+  {sort} values = Nfreq binsize
+    Nfreq = sort atoms spatially every this many time steps
+    binsize = bin size for spatial sorting (distance units) :pre
 :ule
 
 [Examples:]
 
 atom_modify map hash
+atom_modify map array sort 10000 2.0
 atom_modify first colloid :pre
 
 [Description:]
@@ -53,16 +57,55 @@ 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.
+It is OK to use the {first} keyword with a group that has not yet been
+defined, e.g. to use the atom_modify command at the beginning of your
+input script.  LAMMPS will check that the group exists before the
+first simulation is performed.
+
+The {sort} keyword turns on a spatial sorting or reordering of atoms
+within each processor's sub-domain every {Nfreq} timesteps.  This can
+improve cache performance and thus speed=up a LAMMPS simulation, as
+discussed in a paper by "(Meloni)"_#Meloni.  In tests we have done,
+the amount of speed-up can range from zero to 3-4x.  It is typically
+more effective at speeding up simulations of liquids as opposed to
+solids.
+
+Reordering is peformed every {Nfreq} timesteps during a dynamics run
+or iterations during a minimization.  More precisely, reordering
+occurs at the first reneighboring that occurs after the target
+timestep.  The reordering is performed locally by each processor,
+using bins of the specified {binsize}.  If {binsize} is set to 0.0,
+then a binsize equal to half the "neighbor"_neighbor.html cutoff
+distance (force cutoff plus skin distance) is used, which is a
+reasonable value.  After the atoms have been binned, they are
+reordered so that atoms in the same bin are adjacent to each other in
+the processor's 1d list of atoms.
+
+The goal of this procedure is for atoms be near each other in the
+processor's 1d list of atoms that are also near to each other
+spatially.  This can improve cache performance when pairwise
+intereractions and neighbor lists are computed.  Note that if bins are
+too small, there will be few atoms/bin.  Likewise if bins are too
+large, there will be many atoms/bin.  In both cases, the goal of cache
+locality can be undermined.
+
+IMPORTANT NOTE: Running a simulation with sorting on versus off should
+not change the simulation results in a statistical sense.  However,
+reordering will induce round-off differences, which will lead to
+diverging trajectories when comparing two simluations.  Various
+commands, particularly those which use random numbers (e.g. "velocity
+create"_velocity.html, and "fix langevin"_fix_langevin.html), may
+generate different results (but statistically identical) depending on
+the order in which they process atoms.  The order of atoms in a
+"dump"_dump.html file will also change if sorting is enabled.
 
 [Restrictions:]
 
-This command must be used before the simulation box is defined by a
-"read_data"_read_data.html or "create_box"_create_box.html command.
+The map keyword can only be used before the simulation box is defined
+by a "read_data"_read_data.html or "create_box"_create_box.html
+command.
+
+The {first} and {sort} options cannot be used together.
 
 [Related commands:] none
 
@@ -70,4 +113,12 @@ This command must be used before the simulation box is defined by a
 
 By default, atomic (non-molecular) problems do not allocate maps.  For
 molecular problems, the option default is map = array.  By default, a
-"first" group is not defined.
+"first" group is not defined.  By default, sorting is enabled with a
+frequency of 1000 and a binsize of 0.0, which means the neighbor
+cutoff will be used to set the bin size.
+
+:line
+
+:link(Meloni)
+
+[(Meloni)] Meloni and Rasati, J Chem Phys, 126, 121102 (2007).
diff --git a/doc/variable.html b/doc/variable.html
index ad39dc0983..366b507755 100644
--- a/doc/variable.html
+++ b/doc/variable.html
@@ -507,8 +507,8 @@ 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 that is not current, LAMMPS will not do it.
-This means, for example, that such a variable then the variable cannot
-be evaluated before the first run has occurred.
+This means, for example, that such a variable cannot be evaluated
+before the first run has occurred.
 

 
One way to get around this problem is to perform a 0-timestep run
 before using the variable.  For example, these commands
diff --git a/doc/variable.txt b/doc/variable.txt
index 4d6d34caa6..c5ab16b8fa 100644
--- a/doc/variable.txt
+++ b/doc/variable.txt
@@ -496,8 +496,8 @@ 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 not do it.
-This means, for example, that such a variable then the variable cannot
-be evaluated before the first run has occurred.
+This means, for example, that such a variable cannot be evaluated
+before the first run has occurred.
 
 One way to get around this problem is to perform a 0-timestep run
 before using the variable.  For example, these commands