jianmu
/
lammps
forked from lijiext/lammps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update load balance weights documentation for fix balance and balance

This commit is contained in:
Axel Kohlmeyer 2016-09-26 18:33:50 -04:00
parent 2af5c75f42
commit 69a8842ecb
2 changed files with 77 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

109
doc/src/balance.txt
View File

@ -92,7 +92,7 @@ Without any particle weighting, the balancing attempts to assign an
equal number of particles to each processor. With weighting, the
balancing attempts to assign an equal weight to each processor, which
typically means a different number of atoms per processor. Details on
the various weighting options are given below.
the various weighting options are "given below."_#weighted_balance
Note that the "processors"_processors.html command allows some control
over how the box volume is split across processors. Specifically, for
@ -308,56 +308,95 @@ particles in that sub-box.
:line
This sub-section describes how to perform weighted load balancing via
the {weight} keyword.
the {weight} keyword. :link(weighted_balance)
One or more weight factors can be assigned to individual or sets of
particles. By default all particles have an initial weight of 1.0.
After weighting is applied, a particle with a total weight of 5 will
be balanced with 5x the computational cost of a particle with the
default weight of 1.0.
By default, all particles have a weight of 1.0, which means, each
atom is assumed to cause the same amount of work during a time step.
There are, however, scenarios, where this is not a good assumption.
But measuring this computational cost for each particle accurately,
would be impractical and slow down the computation. Instead the
{weight} keyword implements several ways to influence these weights
empirically by properties readily available or using knowledge about
the system. The absolute value of the weights have little meaning;
a particle with a weight of 2.5 will be assumed to cause 5x as much
computational cost than a particle with a weight of 0.5.
If one or more weight styles are specified, they are processed in the
order they are specified. Each style computes a factor which
multiplies the existing factor to produce a cummulative weight on
individual particles.
Below is a list of possible weight options with a short description
of their usage some example scenario, where they might be applicable.
It is possible to apply multiple weight flags and they will be combined
through multiplication. Most of the time, however, it is sufficient
to use just one method.
The {group} weight style assigns weight factors to specified groups of
particles. The {group} style keyword is followed by the number of
groups, then pairs of group IDs and the corresponding weight factor.
A particle may belong to zero or one or more than one specified group.
Its final factor is simply the product of all individual weight
factors for the groups it belongs to.
The {group} weight style assigns weight factors to specified
"groups"_group.html of particles. The {group} style keyword is
followed by the number of groups, then pairs of group IDs and the
corresponding weight factor. If a particle belongs to none of the
specified groups, its weight is untouched, if it belongs to multiple
groups, the weight is the product. This weight style is useful in
combination with pair style "hybrid"_pair_hybrid.html when combining
a more costly manybody potential with a fast pair-wise potential,
or when using run style "respa"_run_style.html where some segments
of the system have many bonded interactions and others none.
It assumes that the computational cost for each group remains the same.
This is a purely empirical weighting, so a series test runs to tune
the assigned weights for optimal performance is recommended.
The {neigh} weight style assigns a weight to each particle equal to
its number of neighbors divided by the avergage number of neighbors
for all particles. The {factor} setting is then appied as an overall
scale factor to all the {neigh} weights. Thus {factor} effectively
sets a relative impact for this weight style. This weight style will
use the first suitable neighbor list it finds internally. It will
print a warning if there is no neighbor list or it is not current,
e.g. if the balance command is used before a "run"_run.html or
"minimize"_minimize.html command is used, which can mean that no
neighbor list has yet been built.
scale factor to all the {neigh} weights and allows to tune the impact
of this method. A {factor} smaller than 1.0 (e.g. 0.8) is often
resulting in the best performance, since the number of neighbors is
likely to overestimate the weights. This weight style is useful
for systems, where there are different cutoffs used for different
pairs of interations or the density fluctuates or a large number of
atoms are in the vicinity of a wall or a combination of those.
This weight style will use the first suitable neighbor list it finds
internally, it will not request or compute a new one. It will print
a warning if there is no such neighbor list available or if it is not
current, e.g. if the balance command is used before a "run"_run.html
or "minimize"_minimize.html command is used, which can mean that no
neighbor list has yet been built. Without a neighbor list, no weight
is computed. Inserting a "run 0 post no"_run.html command before
issuing the {balance} command, might be a workaround for that.
The {time} weight style uses "timer data"_timer.html to calculate a
weight for each particle. The {factor} setting is then appied as an
overall scale factor to all the {time} weights. Effectively it sets a
relative impact for this weight style. Timer information is taken
from the preceding run. NOTE: Entire run or last portion of run?
Which sub-timings within the run? How is it normalized? If no such
information is available, e.g. at the beginning of an input, of when
the "timer"_timer.html level is set to either {loop} or {off}, this
style is ignored.
The {time} weight style uses "timer data"_timer.html to estimate a
weight for each particle. This uses the same information as is used
for the "MPI task timing breakdown"_Section_start.html#start_8,
namely, the sections {Pair}, {Bond}, {Kspace}, and {Neigh}. The time
spend in these sections of the LAMMPS code are measured for each MPI
rank, summed up, converted into a cost for each MPI rank relative to
the average cost over all MPI ranks for the same section, and that
cost is then evenly distributed over the (local) atoms on that rank.
The {factor} setting is then appied as an overall scale factor to
all the {time} weights as a measure to fine tune the impact of this
weight. Typical are {factor} values between 0.5 and 1.2. For the
{balance} command the Timer information is taken from the preceding
run command; with {fix balance} the Timer data since the last balancing
operation is used. If no such information is available, e.g. at
the beginning of an input, of when the "timer"_timer.html level is set
to either {loop} or {off}, this weight style is ignored and the weights
remain unchanged. This weight is the most generic one, and should
be tried first, if neither {group} or {neigh} are easily applicable.
However, since the computed cost function is averaged over all local
atoms it is not always very accurate. It can also be effective as a
secondary weight in combination with either {group} or {neigh} to
offset some of errors in either of those heuristics.
The {var} weight style assigns per-particle weights by evaluating an
atom-style "variable"_variable.html specified by {name}.
atom-style "variable"_variable.html specified by {name}. This is
provided as a more flexible alternative to the {group} weight style,
thus allowing to define more complex heuristics based on information
(global and per atom) available inside of LAMMPS (e.g. position of
a particle, its velocity, volume of voronoi cell, etc.)
The {store} weight style does not compute a weight factor. Instead it
stores the current accumulated weights in a custom per-atom property
specified by {name}. This must be a property defined as {d_name} via
the "fix property/atom"_fix_property_atom.html command. Note that
these custom per-atom properties can be output in a "dump"_dump.html
file, so this is a way to examine per-particle weights.
file, so this is a way to examine, debug and visualized the
per-particle weights computed during the weighting.
:line

73
doc/src/fix_balance.txt
View File

@ -78,14 +78,9 @@ The balancing can be performed with or without per-particle weighting.
Without any particle weighting, the balancing attempts to assign an
equal number of particles to each processor. With weighting, the
balancing attempts to assign an equal weight to each processor, which
typically means a different number of atoms per processor. Details on
the various weighting options are given below.
SJP: Need a pointer here to an examples dir that has simple
examples for where weighting is useful, e.g. rRESPA, pair hybrid,
other? Also a summary of what weighting can buy you, maybe
in a small table: e.g. respa = 2x, pair hybrid = 3x, etc.
All the SJP notes here and below also apply to balance.txt.
typically means a different number of atoms per processor. Details on
the various weighting options and a few use cases are given
"this section of the balance command"_balance.html#weighted_balance
Note that the "processors"_processors.html command allows some control
over how the box volume is split across processors. Specifically, for
@ -281,68 +276,6 @@ in that sub-box.
:line
This sub-section describes how to perform weighted load balancing via
the {weight} keyword.
SJP: This list of options will be confusing to users. They
need some guidelines here about how to use the weight options. E.g.
try these single options first for these scenarios. Try adding
an option if ...
One or more weight factors can be assigned to individual or sets of
particles. By default all particles have an initial weight of 1.0.
After weighting is applied, a particle with a total weight of 5 will
be balanced with 5x the computational cost of a particle with the
default weight of 1.0.
If one or more weight styles are specified, they are processed in the
order they are specified. Each style computes a factor which
multiplies the existing factor to produce a cummulative weight on
individual particles.
The {group} weight style assigns weight factors to specified groups of
particles. The {group} style keyword is followed by the number of
groups, then pairs of group IDs and the corresponding weight factor.
A particle may belong to zero or one or more than one specified group.
Its final factor is simply the product of all individual weight
factors for the groups it belongs to.
The {neigh} weight style assigns a weight to each particle equal to
its number of neighbors divided by the avergage number of neighbors
for all particles. The {factor} setting is then appied as an overall
scale factor to all the {neigh} weights. Thus {factor} effectively
sets a relative impact for this weight style. This weight style will
use the first suitable neighbor list it finds internally. It will
print a warning if there is no neighbor list or it is not current,
e.g. if the balance command is used before a "run"_run.html or
"minimize"_minimize.html command is used, which can mean that no
neighbor list has yet been built.
The {time} weight style uses "timer data"_timer.html to calculate a
weight for each particle. The {factor} setting is then appied as an
overall scale factor to all the {time} weights. Effectively it sets a
relative impact for this weight style. Timer information is taken
from the preceding run. If no such information is available, e.g. at
the beginning of an input, of when the "timer"_timer.html level is set
to either {loop} or {off}, this style is ignored.
SJP: Not enough details about how timer option works. Entire last run
or last portion of run? (for balance vs fix balance) Which sub-timings
within the run, can user choose those? How is it normalized? Does
the timer command need to be specified in a certain way?
The {var} weight style assigns per-particle weights by evaluating an
atom-style "variable"_variable.html specified by {name}.
The {store} weight style does not compute a weight factor. Instead it
stores the current accumulated weights in a custom per-atom property
specified by {name}. This must be a property defined as {d_name} via
the "fix property/atom"_fix_property_atom.html command. Note that
these custom per-atom properties can be output in a "dump"_dump.html
file, so this is a way to examine per-particle weights.
:line
The {out} keyword writes text to the specified {filename} with the
results of each rebalancing operation. The file contains the bounds
of the sub-domain for each processor after the balancing operation