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

doc/Section_errors.html

@@ -6689,12 +6689,12 @@ to lattice.
 
 <DT><I>Use of region with undefined lattice</I> 
 
-<DD>If scale = lattice (the default) for the region command, then a
+<DD>If units = lattice (the default) for the region command, then a
 lattice must first be defined via the lattice command. 
 
 <DT><I>Use of velocity with undefined lattice</I> 
 
-<DD>If scale = lattice (the default) for the velocity set or velocity ramp
+<DD>If units = lattice (the default) for the velocity set or velocity ramp
 command, then a lattice must first be defined via the lattice command. 
 
 <DT><I>Using fix nvt/sllod with inconsistent fix deform remap option</I> 

doc/balance.html

@@ -171,20 +171,26 @@ plane gets closer to the target value.
 assigned, particles are migrated to their new owning processor, and
 the balance procedure ends.
 </P>
-<P>IMPORTANT NOTE: At each rebalance operation, the recursive
-bisectioning operation for each cutting plane (line in 2d) typcially
-starts with low and high bounds separated by the extent of a
-processor's sub-domain in one dimension.  The size of this bracketing
-region shrinks by 1/2 every iteration.  Thus if <I>Niter</I> is specified
-as 10, the cutting plane will typically be positioned to 1 part in
-1000 accuracy (relative to the perfect target position).  For <I>Niter</I>
-= 20, it will be accurate to 1 part in a million.  Tus there is no
-need ot set <I>Niter</I> to a large value.  LAMMPS will check if the
-threshold accuracy is reached (in a dimension) is less iterations than
-<I>Niter</I> and exit early.  However, <I>Niter</I> should also not be set too
-small, since it will take roughly the same number of iterations to
-converge even if the cutting plane is initially close to the target
-value.
+<P>IMPORTANT NOTE: At each rebalance operation, the RCB for each cutting
+plane (line in 2d) typcially starts with low and high bounds separated
+by the extent of a processor's sub-domain in one dimension.  The size
+of this bracketing region shrinks by 1/2 every iteration.  Thus if
+<I>Niter</I> is specified as 10, the cutting plane will typically be
+positioned to 1 part in 1000 accuracy (relative to the perfect target
+position).  For <I>Niter</I> = 20, it will be accurate to 1 part in a
+million.  Tus there is no need ot set <I>Niter</I> to a large value.
+LAMMPS will check if the threshold accuracy is reached (in a
+dimension) is less iterations than <I>Niter</I> and exit early.  However,
+<I>Niter</I> should also not be set too small, since it will take roughly
+the same number of iterations to converge even if the cutting plane is
+initially close to the target value.
+</P>
+<P>IMPORTANT NOTE: If a portion of your system is a perfect lattice,
+e.g. the intiial system is generated by the
+<A HREF = "create_atoms.html">create_atoms</A> command, then the balancer may be
+unable to achieve exact balance.  I.e. entire lattice planes will be
+owned or not owned by a single processor.  So you you should not
+expect to achieve perfect balance in this case.
 </P>
 <HR>
 

doc/balance.txt

@@ -165,20 +165,26 @@ Once the rebalancing is complete and final processor sub-domains
 assigned, particles are migrated to their new owning processor, and
 the balance procedure ends.
 
-IMPORTANT NOTE: At each rebalance operation, the recursive
-bisectioning operation for each cutting plane (line in 2d) typcially
-starts with low and high bounds separated by the extent of a
-processor's sub-domain in one dimension.  The size of this bracketing
-region shrinks by 1/2 every iteration.  Thus if {Niter} is specified
-as 10, the cutting plane will typically be positioned to 1 part in
-1000 accuracy (relative to the perfect target position).  For {Niter}
-= 20, it will be accurate to 1 part in a million.  Tus there is no
-need ot set {Niter} to a large value.  LAMMPS will check if the
-threshold accuracy is reached (in a dimension) is less iterations than
-{Niter} and exit early.  However, {Niter} should also not be set too
-small, since it will take roughly the same number of iterations to
-converge even if the cutting plane is initially close to the target
-value.
+IMPORTANT NOTE: At each rebalance operation, the RCB for each cutting
+plane (line in 2d) typcially starts with low and high bounds separated
+by the extent of a processor's sub-domain in one dimension.  The size
+of this bracketing region shrinks by 1/2 every iteration.  Thus if
+{Niter} is specified as 10, the cutting plane will typically be
+positioned to 1 part in 1000 accuracy (relative to the perfect target
+position).  For {Niter} = 20, it will be accurate to 1 part in a
+million.  Tus there is no need ot set {Niter} to a large value.
+LAMMPS will check if the threshold accuracy is reached (in a
+dimension) is less iterations than {Niter} and exit early.  However,
+{Niter} should also not be set too small, since it will take roughly
+the same number of iterations to converge even if the cutting plane is
+initially close to the target value.
+
+IMPORTANT NOTE: If a portion of your system is a perfect lattice,
+e.g. the intiial system is generated by the
+"create_atoms"_create_atoms.html command, then the balancer may be
+unable to achieve exact balance.  I.e. entire lattice planes will be
+owned or not owned by a single processor.  So you you should not
+expect to achieve perfect balance in this case.
 
 :line
 

doc/fix_balance.html

@@ -125,37 +125,57 @@ is re-computed, and the balancing operation halts if the <I>thresh</I>
 criterion is met.
 </P>
 <P>A rebalance operation in a single dimension is performed using a
-recursive multisectioning algorithm, where the position of each
-cutting plane (line in 2d) in the dimension is adjusted independently.
-This is similar to a recursive bisectioning (RCB) for a single value,
-except that the bounds used for each bisectioning take advantage of
-information from neighboring cuts if possible.  At each iteration, the
-count of particles on either side of each plane is tallied.  If the
-counts do not match the target value for the plane, the position of
-the cut is adjusted to be halfway between a low and high bound.  The
-low and high bounds are adjusted on each iteration, using new count
-information, so that they become closer together over time.  Thus as
-the recustion progresses, the count of particles on either side of the
-plane gets closer to the target value.
+density-dependent recursive multisectioning algorithm, where the
+position of each cutting plane (line in 2d) in the dimension is
+adjusted independently.  This is similar to a recursive bisectioning
+(RCB) for a single value, except that the bounds used for each
+bisectioning take advantage of information from neighboring cuts if
+possible, as well as counts of particles at the bounds on either side
+of each cuts, which themselves were cuts in previous iterations.  The
+latter is used to infer a density of pariticles near each of the
+current cuts.  At each iteration, the count of particles on either
+side of each plane is tallied.  If the counts do not match the target
+value for the plane, the position of the cut is adjusted based on the
+local density.  The low and high bounds are adjusted on each
+iteration, using new count information, so that they become closer
+together over time.  Thus as the recustion progresses, the count of
+particles on either side of the plane gets closer to the target value.
+</P>
+<P>The density-dependent part of this algorithm is often an advantage
+when you rebalance a system that is already nearly balanced.  It
+typically converges more quickly than the geometric bisectioning
+algorithm used by the <A HREF = "balance.html">balance</A> command.  However, if can
+be a disadvants if you attempt to rebalance a system that is far from
+balanced, and converge more slowly.  In this case you probably want to
+use the <A HREF = "balance.html">balance</A> command before starting a run, so that
+you begin the run with a balanced system.
 </P>
 <P>Once the rebalancing is complete and final processor sub-domains
 assigned, particles migrate to their new owning processor as part of
 the normal reneighboring procedure.
 </P>
-<P>IMPORTANT NOTE: At each rebalance operation, the recursive
-bisectioning operation for each cutting plane (line in 2d) typcially
-starts with low and high bounds separated by the extent of a
-processor's sub-domain in one dimension.  The size of this bracketing
-region shrinks by 1/2 every iteration.  Thus if <I>Niter</I> is specified
-as 10, the cutting plane will typically be positioned to 1 part in
-1000 accuracy (relative to the perfect target position).  For <I>Niter</I>
-= 20, it will be accurate to 1 part in a million.  Thus there is no
-need to set <I>Niter</I> to a large value.  LAMMPS will check if the
-threshold accuracy is reached (in a dimension) is less iterations than
-<I>Niter</I> and exit early.  However, <I>Niter</I> should also not be set too
-small, since it will take roughly the same number of iterations to
-converge even if the cutting plane is initially close to the target
-value.
+<P>IMPORTANT NOTE: At each rebalance operation, the RCB operation for
+each cutting plane (line in 2d) typcially starts with low and high
+bounds separated by the extent of a processor's sub-domain in one
+dimension.  The size of this bracketing region shrinks based on the
+local density, as described above, which should typically be 1/2 or
+more every iteration.  Thus if <I>Niter</I> is specified as 10, the cutting
+plane will typically be positioned to better than 1 part in 1000
+accuracy (relative to the perfect target position).  For <I>Niter</I> = 20,
+it will be accurate to better than 1 part in a million.  Thus there is
+no need to set <I>Niter</I> to a large value.  This is especially true if
+you are rebalancing often enough that each time you expect only an
+incremental adjustement in the cutting planes is necessary.  LAMMPS
+will check if the threshold accuracy is reached (in a dimension) is
+less iterations than <I>Niter</I> and exit early.
+</P>
+<P>IMPORTANT NOTE: If a portion of your system is a perfect lattice,
+e.g. a frozen substrate, then the balancer may be unable to achieve
+exact balance.  I.e. entire lattice planes will be owned or not owned
+by a single processor.  So you you should not expect to achieve
+perfect balance in this case.  Nor will it be helpful to use a large
+value for <I>Niter</I>, since it will simply cause the balancer to iterate
+until <I>Niter</I> is reached, without improving the imbalance factor.
 </P>
 <HR>
 

doc/fix_balance.txt

@@ -113,37 +113,57 @@ is re-computed, and the balancing operation halts if the {thresh}
 criterion is met.
 
 A rebalance operation in a single dimension is performed using a
-recursive multisectioning algorithm, where the position of each
-cutting plane (line in 2d) in the dimension is adjusted independently.
-This is similar to a recursive bisectioning (RCB) for a single value,
-except that the bounds used for each bisectioning take advantage of
-information from neighboring cuts if possible.  At each iteration, the
-count of particles on either side of each plane is tallied.  If the
-counts do not match the target value for the plane, the position of
-the cut is adjusted to be halfway between a low and high bound.  The
-low and high bounds are adjusted on each iteration, using new count
-information, so that they become closer together over time.  Thus as
-the recustion progresses, the count of particles on either side of the
-plane gets closer to the target value.
+density-dependent recursive multisectioning algorithm, where the
+position of each cutting plane (line in 2d) in the dimension is
+adjusted independently.  This is similar to a recursive bisectioning
+(RCB) for a single value, except that the bounds used for each
+bisectioning take advantage of information from neighboring cuts if
+possible, as well as counts of particles at the bounds on either side
+of each cuts, which themselves were cuts in previous iterations.  The
+latter is used to infer a density of pariticles near each of the
+current cuts.  At each iteration, the count of particles on either
+side of each plane is tallied.  If the counts do not match the target
+value for the plane, the position of the cut is adjusted based on the
+local density.  The low and high bounds are adjusted on each
+iteration, using new count information, so that they become closer
+together over time.  Thus as the recustion progresses, the count of
+particles on either side of the plane gets closer to the target value.
+
+The density-dependent part of this algorithm is often an advantage
+when you rebalance a system that is already nearly balanced.  It
+typically converges more quickly than the geometric bisectioning
+algorithm used by the "balance"_balance.html command.  However, if can
+be a disadvants if you attempt to rebalance a system that is far from
+balanced, and converge more slowly.  In this case you probably want to
+use the "balance"_balance.html command before starting a run, so that
+you begin the run with a balanced system.
 
 Once the rebalancing is complete and final processor sub-domains
 assigned, particles migrate to their new owning processor as part of
 the normal reneighboring procedure.
 
-IMPORTANT NOTE: At each rebalance operation, the recursive
-bisectioning operation for each cutting plane (line in 2d) typcially
-starts with low and high bounds separated by the extent of a
-processor's sub-domain in one dimension.  The size of this bracketing
-region shrinks by 1/2 every iteration.  Thus if {Niter} is specified
-as 10, the cutting plane will typically be positioned to 1 part in
-1000 accuracy (relative to the perfect target position).  For {Niter}
-= 20, it will be accurate to 1 part in a million.  Thus there is no
-need to set {Niter} to a large value.  LAMMPS will check if the
-threshold accuracy is reached (in a dimension) is less iterations than
-{Niter} and exit early.  However, {Niter} should also not be set too
-small, since it will take roughly the same number of iterations to
-converge even if the cutting plane is initially close to the target
-value.
+IMPORTANT NOTE: At each rebalance operation, the RCB operation for
+each cutting plane (line in 2d) typcially starts with low and high
+bounds separated by the extent of a processor's sub-domain in one
+dimension.  The size of this bracketing region shrinks based on the
+local density, as described above, which should typically be 1/2 or
+more every iteration.  Thus if {Niter} is specified as 10, the cutting
+plane will typically be positioned to better than 1 part in 1000
+accuracy (relative to the perfect target position).  For {Niter} = 20,
+it will be accurate to better than 1 part in a million.  Thus there is
+no need to set {Niter} to a large value.  This is especially true if
+you are rebalancing often enough that each time you expect only an
+incremental adjustement in the cutting planes is necessary.  LAMMPS
+will check if the threshold accuracy is reached (in a dimension) is
+less iterations than {Niter} and exit early.
+
+IMPORTANT NOTE: If a portion of your system is a perfect lattice,
+e.g. a frozen substrate, then the balancer may be unable to achieve
+exact balance.  I.e. entire lattice planes will be owned or not owned
+by a single processor.  So you you should not expect to achieve
+perfect balance in this case.  Nor will it be helpful to use a large
+value for {Niter}, since it will simply cause the balancer to iterate
+until {Niter} is reached, without improving the imbalance factor.
 
 :line