Commit d80a9def authored by Axel Kohlmeyer's avatar Axel Kohlmeyer
Browse files

Version 5 Oct 2016

parents be4734bd 02bfa898
Loading
Loading
Loading
Loading
+2 −2
Original line number Diff line number Diff line
<!-- HTML_ONLY -->
<HEAD>
<TITLE>LAMMPS Users Manual</TITLE>
<META NAME="docnumber" CONTENT="29 Sep 2016 version">
<META NAME="docnumber" CONTENT="5 Oct 2016 version">
<META NAME="author" CONTENT="http://lammps.sandia.gov - Sandia National Laboratories">
<META NAME="copyright" CONTENT="Copyright (2003) Sandia Corporation.  This software and manual is distributed under the GNU General Public License.">
</HEAD>
@@ -21,7 +21,7 @@
<H1></H1>

LAMMPS Documentation :c,h3
29 Sep 2016 version :c,h4
5 Oct 2016 version :c,h4

Version info: :h4

+2 −2
Original line number Diff line number Diff line
@@ -896,7 +896,7 @@ KOKKOS, o = USER-OMP, t = OPT.
"lubricate/poly (o)"_pair_lubricate.html,
"lubricateU"_pair_lubricateU.html,
"lubricateU/poly"_pair_lubricateU.html,
"meam (o)"_pair_meam.html,
"meam"_pair_meam.html,
"mie/cut (o)"_pair_mie.html,
"morse (got)"_pair_morse.html,
"nb3b/harmonic (o)"_pair_nb3b_harmonic.html,
@@ -956,7 +956,7 @@ package"_Section_start.html#start_3.
"lj/sdk/coul/long (go)"_pair_sdk.html,
"lj/sdk/coul/msm (o)"_pair_sdk.html,
"lj/sf (o)"_pair_lj_sf.html,
"meam/spline"_pair_meam_spline.html,
"meam/spline (o)"_pair_meam_spline.html,
"meam/sw/spline"_pair_meam_sw_spline.html,
"mgpt"_pair_mgpt.html,
"morse/smooth/linear"_pair_morse.html,
+67 −41
Original line number Diff line number Diff line
@@ -319,14 +319,16 @@ accurately would be impractical and slow down the computation.
Instead the {weight} keyword implements several ways to influence the
per-particle weights empirically by properties readily available or
using the user's knowledge of the system.  Note that the absolute
value of the weights are not important; their ratio is what is used to
assign particles to processors.  A particle with a weight of 2.5 is
assumed to require 5x more computational than a particle with a weight
of 0.5.
value of the weights are not important; only their relative ratios
affect which particle is assigned to which processor.  A particle with
a weight of 2.5 is assumed to require 5x more computational than a
particle with a weight of 0.5.  For all the options below the weight
assigned to a particle must be a positive value; an error will be be
generated if a weight is <= 0.0.

Below is a list of possible weight options with a short description of
their usage and some example scenarios where they might be applicable.
It is possible to apply multiple weight flags and the weightins they
It is possible to apply multiple weight flags and the weightings they
induce will be combined through multiplication.  Most of the time,
however, it is sufficient to use just one method.

@@ -346,13 +348,24 @@ the computational cost for each group remains constant over time.
This is a purely empirical weighting, so a series test runs to tune
the assigned weight factors 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 which allows tuning of the
impact of this style.  A {factor} smaller than 1.0 (e.g. 0.8) often
results in the best performance, since the number of neighbors is
likely to overestimate the ideal weight.
The {neigh} weight style assigns the same weight to each particle
owned by a processor based on the total count of neighbors in the
neighbor list owned by that processor.  The motivation is that more
neighbors means a higher computational cost.  The style does not use
neighbors per atom to assign a unique weight to each atom, because
that value can vary depending on how the neighbor list is built.

The {factor} setting is applied as an overall scale factor to the
{neigh} weights which allows adjustment of their impact on the
balancing operation.  The specified {factor} value must be positive.
A value > 1.0 will increase the weights so that the ratio of max
weight to min weight increases by {factor}.  A value < 1.0 will
decrease the weights so that the ratio of max weight to min weight
decreases by {factor}.  In both cases the intermediate weight values
increase/decrease proportionally as well.  A value = 1.0 has no effect
on the {neigh} weights.  As a rule of thumb, we have found a {factor}
of about 0.8 often results in the best performance, since the number
of neighbors is likely to overestimate the ideal weight.

This weight style is useful for systems where there are different
cutoffs used for different pairs of interations, or the density
@@ -368,35 +381,48 @@ weights are computed. Inserting a "run 0 post no"_run.html command
before issuing the {balance} command, may be a workaround for this
case, as it will induce the neighbor list to be built.

The {time} weight style uses "timer data"_timer.html to estimate a
weight for each particle.  It uses the same information as is used for
the "MPI task timing breakdown"_Section_start.html#start_8, namely,
the timings for sections {Pair}, {Bond}, {Kspace}, and {Neigh}.  The
time spent in these sections of the timestep are measured for each MPI
rank, summed up, then converted into a cost for each MPI rank relative
to the average cost over all MPI ranks for the same sections.  That
cost then evenly distributed over all the particles owned by that
rank.  Finally, the {factor} setting is then appied as an overall
scale factor to all the {time} weights as a way to fine tune the
impact of this weight style.  Good {factor} values to use are
typically between 0.5 and 1.2.

For the {balance} command the timing data is taken from the preceding
run command, i.e. the timings are for the entire previous run.  For
the {fix balance} command the timing data is for only the timesteps
since the last balancing operation was performed.  If timing
information for the required sections is not available, e.g. at the
beginning of a run, or when the "timer"_timer.html command is set to
either {loop} or {off}, a warning is issued.  In this case no weights
are computed.

This weight style is the most generic one, and should be tried first,
if neither the {group} or {neigh} styles are easily applicable.
However, since the computed cost function is averaged over all local
particles this weight style may not be highly accurate.  This style
can also be effective as a secondary weight in combination with either
{group} or {neigh} to offset some of inaccuracies in either of those
heuristics.
The {time} weight style uses "timer data"_timer.html to estimate
weights.  It assigns the same weight to each particle owned by a
processor based on the total computational time spent by that
processor.  See details below on what time window is used.  It uses
the same timing information as is used for the "MPI task timing
breakdown"_Section_start.html#start_8, namely, for sections {Pair},
{Bond}, {Kspace}, and {Neigh}.  The time spent in those portions of
the timestep are measured for each MPI rank, summed, then divided by
the number of particles owned by that processor.  I.e. the weight is
an effective CPU time/particle averaged over the particles on that
processor.

The {factor} setting is applied as an overall scale factor to the
{time} weights which allows adjustment of their impact on the
balancing operation.  The specified {factor} value must be positive.
A value > 1.0 will increase the weights so that the ratio of max
weight to min weight increases by {factor}.  A value < 1.0 will
decrease the weights so that the ratio of max weight to min weight
decreases by {factor}.  In both cases the intermediate weight values
increase/decrease proportionally as well.  A value = 1.0 has no effect
on the {time} weights.  As a rule of thumb, effective values to use
are typicall between 0.5 and 1.2.  Note that the timer quantities
mentioned above can be affected by communication which occurs in the
middle of the operations, e.g. pair styles with intermediate exchange
of data witin the force computation, and likewise for KSpace solves.

When using the {time} weight style with the {balance} command, the
timing data is taken from the preceding run command, i.e. the timings
are for the entire previous run.  For the {fix balance} command the
timing data is for only the timesteps since the last balancing
operation was performed.  If timing information for the required
sections is not available, e.g. at the beginning of a run, or when the
"timer"_timer.html command is set to either {loop} or {off}, a warning
is issued.  In this case no weights are computed.

NOTE: The {time} weight style is the most generic option, and should
be tried first, unless the {group} style is easily applicable.
However, since the computed cost function is averaged over all
particles on a processor, the weights may not be highly accurate.
This style can also be effective as a secondary weight in combination
with either {group} or {neigh} to offset some of inaccuracies in
either of those heuristics.

The {var} weight style assigns per-particle weights by evaluating an
"atom-style variable"_variable.html specified by {name}.  This is
+50 −7
Original line number Diff line number Diff line
@@ -49,8 +49,8 @@ keyword = {append} or {buffer} or {element} or {every} or {fileper} or {first} o
     -N = sort per-atom lines in descending order by the Nth column
  {thresh} args = attribute operation value
    attribute = same attributes (x,fy,etotal,sxx,etc) used by dump custom style
    operation = "<" or "<=" or ">" or ">=" or "==" or "!="
    value = numeric value to compare to
    operation = "<" or "<=" or ">" or ">=" or "==" or "!=" or "|^"
    value = numeric value to compare to, or LAST
    these 3 args can be replaced by the word "none" to turn off thresholding
  {unwrap} arg = {yes} or {no} :pre
these keywords apply only to the {image} and {movie} "styles"_dump_image.html :l
@@ -458,16 +458,59 @@ as well as memory, versus unsorted output.

The {thresh} keyword only applies to the dump {custom}, {cfg},
{image}, and {movie} styles.  Multiple thresholds can be specified.
Specifying "none" turns off all threshold criteria.  If thresholds are
Specifying {none} turns off all threshold criteria.  If thresholds are
specified, only atoms whose attributes meet all the threshold criteria
are written to the dump file or included in the image.  The possible
attributes that can be tested for are the same as those that can be
specified in the "dump custom"_dump.html command, with the exception
of the {element} attribute, since it is not a numeric value.  Note
that different attributes can be output by the dump custom command
than are used as threshold criteria by the dump_modify command.
E.g. you can output the coordinates and stress of atoms whose energy
is above some threshold.
that a different attributes can be used than those output by the "dump
custom"_dump.html command.  E.g. you can output the coordinates and
stress of atoms whose energy is above some threshold.

If an atom-style variable is used as the attribute, then it can
produce continuous numeric values or effective Boolean 0/1 values
which may be useful for the comparision operation.  Boolean values can
be generated by variable formulas that use comparison or Boolean math
operators or special functions like gmask() and rmask() and grmask().
See the "variable"_variable.html command doc page for details.

NOTE: The LAST option, discussed below, is not yet implemented.  It
will be soon.

The specified value must be a simple numeric value or the word LAST.
If LAST is used, it refers to the value of the attribute the last time
the dump command was invoked to produce a snapshot.  This is a way to
only dump atoms whose attribute has changed (or not changed).
Three examples follow.

dump_modify ... thresh ix != LAST :pre

This will dump atoms which have crossed the periodic x boundary of the
simulation box since the last dump.  (Note that atoms that crossed
once and then crossed back between the two dump timesteps would not be
included.)

region foo sphere 10 20 10 15 
variable inregion atom rmask(foo)
dump_modify ... thresh v_inregion |^ LAST

This will dump atoms which crossed the boundary of the spherical
region since the last dump.

variable charge atom "(q > 0.5) || (q < -0.5)"
dump_modify ... thresh v_charge |^ LAST

This will dump atoms whose charge has changed from an absolute value
less than 1/2 to greater than 1/2 (or vice versa) since the last dump.
E.g. due to reactions and subsequent charge equilibration in a
reactive force field.

The choice of operations are the usual comparison operators.  The XOR
operation (exclusive or) is also included as "|^".  In this context,
XOR means that if either the attribute or value is 0.0 and the other
is non-zero, then the result is "true" and the threshold criterion is
met.  Otherwise it is not met.

:line

+10 −7
Original line number Diff line number Diff line
@@ -139,7 +139,7 @@ InP, myString, a123, ab_23_cd, etc :pre

and Boolean operators:

A == B, A != B, A < B, A <= B, A > B, A >= B, A && B, A || B, !A :pre
A == B, A != B, A < B, A <= B, A > B, A >= B, A && B, A || B, A |^ B, !A :pre

Each A and B is a number or string or a variable reference like $a or
$\{abc\}, or A or B can be another Boolean expression.
@@ -155,9 +155,10 @@ precedence: the unary logical NOT operator "!" has the highest
precedence, the 4 relational operators "<", "<=", ">", and ">=" are
next; the two remaining relational operators "==" and "!=" are next;
then the logical AND operator "&&"; and finally the logical OR
operator "||" has the lowest precedence.  Parenthesis can be used to
group one or more portions of an expression and/or enforce a different
order of evaluation than what would occur with the default precedence.
operator "||" and logical XOR (exclusive or) operator "|^" have the
lowest precedence.  Parenthesis can be used to group one or more
portions of an expression and/or enforce a different order of
evaluation than what would occur with the default precedence.

When the 6 relational operators (first 6 in list above) compare 2
numbers, they return either a 1.0 or 0.0 depending on whether the
@@ -171,9 +172,11 @@ relationship between A and B is TRUE or FALSE (or just A). The
logical AND operator will return 1.0 if both its arguments are
non-zero, else it returns 0.0.  The logical OR operator will return
1.0 if either of its arguments is non-zero, else it returns 0.0.  The
logical NOT operator returns 1.0 if its argument is 0.0, else it
returns 0.0.  The 3 logical operators can only be used to operate on
numbers, not on strings.
logical XOR operator will return 1.0 if one of its arguments is zero
and the other non-zero, else it returns 0.0.  The logical NOT operator
returns 1.0 if its argument is 0.0, else it returns 0.0.  The 3
logical operators can only be used to operate on numbers, not on
strings.

The overall Boolean expression produces a TRUE result if the result is
non-zero.  If the result is zero, the expression result is FALSE.
Loading