From dfdc3fe1a2d4141e41e7ab410cd6b6145e5750ea Mon Sep 17 00:00:00 2001
From: sjplimp <sjplimp@f3b2605a-c512-4ea7-a41b-209d697bcdaa>
Date: Tue, 13 Dec 2011 17:03:43 +0000
Subject: [PATCH] git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@7344
 f3b2605a-c512-4ea7-a41b-209d697bcdaa

---
 doc/processors.html | 41 ++++++++++++++++++++++-------------------
 doc/processors.txt  | 41 ++++++++++++++++++++++-------------------
 doc/run_style.html  |  5 +++--
 doc/run_style.txt   |  5 +++--
 4 files changed, 50 insertions(+), 42 deletions(-)

diff --git a/doc/processors.html b/doc/processors.html
index 4a141d8315..7975a73126 100644
--- a/doc/processors.html
+++ b/doc/processors.html
@@ -15,24 +15,32 @@
 </P>
 <PRE>processors Px Py Pz keyword args ... 
 </PRE>
-<UL><LI>Px,Py,Pz = # of processors in each dimension of a 3d grid 
+<UL><LI>Px,Py,Pz = # of processors in each dimension of 3d grid overlaying the simulation domain 
 
 <LI>zero or more keyword/arg pairs may be appended 
 
-<LI>keyword = <I>grid</I> or <I>level2</I> or <I>level3</I> or <I>numa</I> or <I>part</I> or <I>file</I> 
+<LI>keyword = <I>grid</I> or <I>map</I> or <I>part</I> or <I>file</I> 
 
-<PRE>  <I>grid</I> arg = <I>cart</I> or <I>cart/reorder</I> or <I>xyz</I> or <I>xzy</I> or <I>yxz</I> or <I>yzx</I> or <I>zxy</I> or <I>zyx</I>
-     cart = use MPI_Cart() methods to layout 3d grid of procs with reorder = 0
-     cart/reorder = use MPI_Cart() methods to layout 3d grid of procs with reorder = 1
-     xyz,xzy,yxz,yzx,zxy,zyx = layout 3d grid of procs in IJK order
+<PRE>  <I>grid</I> arg = gstyle params ...
+    gstyle = <I>onelevel</I> or <I>twolevel</I> or <I>numa</I> or <I>custom</I>
+      onelevel params = none
+      twolevel params = Cx Cy Cz
+        Cx,Cy,Cz = # of cores in each dimension of 3d sub-grid assigned to each node
+      numa params = none
+      custom params = fname
+        fname = file containing grid layout
+  <I>map</I> arg = <I>cart</I> or <I>cart/reorder</I> or <I>xyz</I> or <I>xzy</I> or <I>yxz</I> or <I>yzx</I> or <I>zxy</I> or <I>zyx</I>
+     cart = use MPI_Cart() methods to map processors to 3d grid with reorder = 0
+     cart/reorder = use MPI_Cart() methods to map processors to 3d grid with reorder = 1
+     xyz,xzy,yxz,yzx,zxy,zyx = map procesors to 3d grid in IJK ordering
   <I>numa</I> arg = none
   <I>part</I> args = Psend Precv cstyle
     Psend = partition # (1 to Np) which will send its processor layout
     Precv = partition # (1 to Np) which will recv the processor layout
     cstyle = <I>multiple</I>
-      <I>multiple</I> = Psend layout will be multiple of Precv layout in each dimension
-  <I>file</I> arg = fname
-    fname = name of file to write processor mapping info to 
+      <I>multiple</I> = Psend grid will be multiple of Precv grid in each dimension
+  <I>file</I> arg = outname
+    outname = name of file to write 3d grid of processors to 
 </PRE>
 
 </UL>
@@ -40,10 +48,9 @@
 </P>
 <PRE>processors * * 5 
 processors 2 4 4
-processors 2 4 4 grid xyz
-processors * * 8 grid xyz
-processors * * * numa
-processors 4 8 16 custom myfile
+processors * * 8 map xyz
+processors * * * grid numa
+processors 4 8 16 grid custom myfile
 processors * * * part 1 2 multiple 
 </PRE>
 <P><B>Description:</B>
@@ -238,11 +245,7 @@ same <I>name</I>.
 It can be used before a restart file is read to change the 3d
 processor grid from what is specified in the restart file.
 </P>
-<P>You cannot use more than one of the <I>level2</I>, <I>level3</I>, or <I>numa</I>
-keywords.
-</P>
-<P>The <I>numa</I> keyword cannot be used with the <I>part</I> keyword, and it
-ignores the <I>grid</I> setting.
+<P>The <I>grid numa</I> keyword only currently works with the <I>map cart</I> option.
 </P>
 <P><B>Related commands:</B>
 </P>
@@ -251,6 +254,6 @@ switch</A>
 </P>
 <P><B>Default:</B>
 </P>
-<P>The option defaults are Px Py Pz = * * * and grid = cart.
+<P>The option defaults are Px Py Pz = * * *, grid = level1, and map = cart.
 </P>
 </HTML>
diff --git a/doc/processors.txt b/doc/processors.txt
index 946a5d1853..1ed1041871 100644
--- a/doc/processors.txt
+++ b/doc/processors.txt
@@ -12,31 +12,38 @@ processors command :h3
 
 processors Px Py Pz keyword args ... :pre
 
-Px,Py,Pz = # of processors in each dimension of a 3d grid :ulb,l
+Px,Py,Pz = # of processors in each dimension of 3d grid overlaying the simulation domain :ulb,l
 zero or more keyword/arg pairs may be appended :l
-keyword = {grid} or {level2} or {level3} or {numa} or {part} or {file} :l
-  {grid} arg = {cart} or {cart/reorder} or {xyz} or {xzy} or {yxz} or {yzx} or {zxy} or {zyx}
-     cart = use MPI_Cart() methods to layout 3d grid of procs with reorder = 0
-     cart/reorder = use MPI_Cart() methods to layout 3d grid of procs with reorder = 1
-     xyz,xzy,yxz,yzx,zxy,zyx = layout 3d grid of procs in IJK order
+keyword = {grid} or {map} or {part} or {file} :l
+  {grid} arg = gstyle params ...
+    gstyle = {onelevel} or {twolevel} or {numa} or {custom}
+      onelevel params = none
+      twolevel params = Cx Cy Cz
+        Cx,Cy,Cz = # of cores in each dimension of 3d sub-grid assigned to each node
+      numa params = none
+      custom params = fname
+        fname = file containing grid layout
+  {map} arg = {cart} or {cart/reorder} or {xyz} or {xzy} or {yxz} or {yzx} or {zxy} or {zyx}
+     cart = use MPI_Cart() methods to map processors to 3d grid with reorder = 0
+     cart/reorder = use MPI_Cart() methods to map processors to 3d grid with reorder = 1
+     xyz,xzy,yxz,yzx,zxy,zyx = map procesors to 3d grid in IJK ordering
   {numa} arg = none
   {part} args = Psend Precv cstyle
     Psend = partition # (1 to Np) which will send its processor layout
     Precv = partition # (1 to Np) which will recv the processor layout
     cstyle = {multiple}
-      {multiple} = Psend layout will be multiple of Precv layout in each dimension
-  {file} arg = fname
-    fname = name of file to write processor mapping info to :pre
+      {multiple} = Psend grid will be multiple of Precv grid in each dimension
+  {file} arg = outname
+    outname = name of file to write 3d grid of processors to :pre
 :ule
 
 [Examples:]
 
 processors * * 5 
 processors 2 4 4
-processors 2 4 4 grid xyz
-processors * * 8 grid xyz
-processors * * * numa
-processors 4 8 16 custom myfile
+processors * * 8 map xyz
+processors * * * grid numa
+processors 4 8 16 grid custom myfile
 processors * * * part 1 2 multiple :pre
 
 [Description:]
@@ -231,11 +238,7 @@ This command cannot be used after the simulation box is defined by a
 It can be used before a restart file is read to change the 3d
 processor grid from what is specified in the restart file.
 
-You cannot use more than one of the {level2}, {level3}, or {numa}
-keywords.
-
-The {numa} keyword cannot be used with the {part} keyword, and it
-ignores the {grid} setting.
+The {grid numa} keyword only currently works with the {map cart} option.
 
 [Related commands:]
 
@@ -244,4 +247,4 @@ switch"_Section_start.html#start_6
 
 [Default:]
 
-The option defaults are Px Py Pz = * * * and grid = cart.
+The option defaults are Px Py Pz = * * *, grid = level1, and map = cart.
diff --git a/doc/run_style.html b/doc/run_style.html
index f885210b2b..0fb15a4541 100644
--- a/doc/run_style.html
+++ b/doc/run_style.html
@@ -123,8 +123,9 @@ output beyone the 1st timestep of the run.
 performance details of the speed-up offered by the <I>verlet/split</I>
 style.  One important performance consideration is the assignemnt of
 logical processors in the 2 partitions to the physical cores of a
-parallel machine.  <A HREF = "Section_accelerate.html">This section</A> discusses
-how to optimize this mapping.
+parallel machine.  The <A HREF = "processors.html">processors</A> command has
+options to support this, and strategies are discussed in
+<A HREF = "Section_accelerate.html">Section_accelerate</A> of the manual.
 </P>
 <HR>
 
diff --git a/doc/run_style.txt b/doc/run_style.txt
index ea9715d821..7e7b792a7c 100644
--- a/doc/run_style.txt
+++ b/doc/run_style.txt
@@ -118,8 +118,9 @@ See "this section"_Section_accelerate.html of the manual for
 performance details of the speed-up offered by the {verlet/split}
 style.  One important performance consideration is the assignemnt of
 logical processors in the 2 partitions to the physical cores of a
-parallel machine.  "This section"_Section_accelerate.html discusses
-how to optimize this mapping.
+parallel machine.  The "processors"_processors.html command has
+options to support this, and strategies are discussed in
+"Section_accelerate"_Section_accelerate.html of the manual.
 
 :line