update documentation according to the modified implementation based on iain...

    stopthresh = stop balancing when this imbalance threshhold is reached

  {rcb} args = none :pre

zero or more keyword/value pairs may be appended :l

keyword = {out} :l

keyword = {out} or {group} :l

  {out} value = filename

    filename = write each processor's sub-domain to a file :pre

    filename = write each processor's sub-domain to a file

  {group} args = Ngroup groupID-1 weight-1 groupID-2 weight-2...

    Ngroup = number of groups with assigned weights

    groupID-1, groupID-2, ... = group names

    weight-1, weight-2, ...   = corresponding weight factors :pre

:ule

[Examples:]

balance 1.2 shift xz 5 1.1

balance 1.0 shift xz 5 1.1

balance 1.1 rcb

balance 1.0 shift x 10 1.1 group 2 fast 0.5 slow 2.0

balance 1.0 shift x 20 1.0 out tmp.balance :pre

[Description:]

This command adjusts the size and shape of processor sub-domains

within the simulation box, to attempt to balance the number of

particles and thus the computational cost (load) evenly across

processors.  The load balancing is "static" in the sense that this

command performs the balancing once, before or between simulations.

particles and thus indirectly the computational cost (load)

more evenly across processors.  The load balancing is "static"

in the sense that this command performs the balancing once, before

or between simulations.

The processor sub-domains will then remain static during the

subsequent run.  To perform "dynamic" balancing, see the "fix

balance"_fix_balance.html command, which can adjust processor

sub-domain sizes and shapes on-the-fly during a "run"_run.html.

NOTE: If a particle is part of a "group"_group.html where a non-unity

{load_factor} is set, those particles are weighted when the load

balancer counts particles in each sub-domain.  Thus a particle with a

weight of 10 counts as much as 10 normal particles.

Load-balancing is typically only useful if the particles in the

simulation box have a spatially-varying density distribution.  E.g. a

model of a vapor/liquid interface, or a solid with an irregular-shaped

geometry containing void regions.  In this case, the LAMMPS default of

dividing the simulation box volume into a regular-spaced grid of 3d

bricks, with one equal-volume sub-domain per procesor, may assign very

different numbers of particles per processor.  This can lead to poor

performance when the simulation is run in parallel.

With the optional {group} keyword different weight factors can be

assigned to particles according to which groups they belong to.

The {group} keyword is followed by the number of groups with

custom weights (default weight is 1.0) and pairs of group ID and

the corresponding weight factor. The final weight for each atom

is the product of all weight factors from the groups it belongs to.

An atom with a total weight of 5 then be will be considered to

have 5x the computational cost than an atom with the default weight

of 1.0.

Load-balancing is typically most useful if the particles in the

simulation box have a spatially-varying density distribution or

where the computational cost varies signficantly between different

atoms. E.g. a model of a vapor/liquid interface, or a solid with

an irregular-shaped geometry containing void regions, or

"hybrid pair style simulations"_pair_hybrid.html which combine

pair styles with different computational cost.  In these cases, the

LAMMPS default of dividing the simulation box volume into a

regular-spaced grid of 3d bricks, with one equal-volume sub-domain

per procesor, may assign numbers of particles per processor in a

way that the computational effort varies significantly.  This can

lead to poor performance when the simulation is run in parallel.

Note that the "processors"_processors.html command allows some control

over how the box volume is split across processors.  Specifically, for

may not be achieved.  For example, "grid" methods (defined below) that

create a logical 3d grid cannot achieve perfect balance for many

irregular distributions of particles.  Likewise, if a portion of the

system is a perfect lattice, e.g. the intiial system is generated by

system is a perfect lattice, e.g. the initial system is generated by

the "create_atoms"_create_atoms.html command, then "grid" methods may

be unable to achieve exact balance.  This is because entire lattice

planes will be owned or not owned by a single processor.

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

the recursion progresses, the count of particles on either side of the

plane gets closer to the target value.

Once the rebalancing is complete and final processor sub-domains

    stopthresh = stop balancing when this imbalance threshhold is reached

  rcb args = none :pre

zero or more keyword/value pairs may be appended :l

keyword = {out} :l

keyword = {out} or {group} :l

  {out} value = filename

    filename = write each processor's sub-domain to a file, at each re-balancing :pre

    filename = write each processor's sub-domain to a file, at each re-balancing

  {group} args = Ngroup groupID-1 weight-1 groupID-2 weight-2...

    Ngroup = number of groups with assigned weights

    groupID-1, groupID-2, ... = group names

    weight-1, weight-2, ...   = corresponding weights :pre

:ule

[Examples:]

fix 2 all balance 1000 1.05 shift x 10 1.05

fix 2 all balance 100 0.9 shift xy 20 1.1 out tmp.balance

fix 2 all balance 100 0.9 shift xy 20 1.1 group 3 substrate 3.0 solvent 1.0 solute 0.8 out tmp.balance

fix 2 all balance 1000 1.1 rcb :pre

[Description:]

perform "static" balancing, before or between runs, see the

"balance"_balance.html command.

NOTE: If a particle is part of a "group"_group.html where a non-unity

{load_factor} is set, those particles are weighted when the load

balancer counts particles in each sub-domain.  Thus a particle with a

weight of 10 counts as much as 10 normal particles.

Load-balancing is typically only useful if the particles in the

simulation box have a spatially-varying density distribution.  E.g. a

model of a vapor/liquid interface, or a solid with an irregular-shaped

geometry containing void regions.  In this case, the LAMMPS default of

dividing the simulation box volume into a regular-spaced grid of 3d

bricks, with one equal-volume sub-domain per processor, may assign

very different numbers of particles per processor.  This can lead to

poor performance when the simulation is run in parallel.

With the optional {group} keyword different weight factors can be

assigned to particles according to which groups they belong to.

The {group} keyword is followed by the number of groups with

custom weights (default weight is 1.0) and pairs of group ID and

the corresponding weight factor. The final weight for each atom

is the product of all weight factors from the groups it belongs to.

An atom with a total weight of 5 then be will be considered to

have 5x the computational cost than an atom with the default weight

of 1.0.

Load-balancing is typically most useful if the particles in the

simulation box have a spatially-varying density distribution or

where the computational cost varies signficantly between different

atoms. E.g. a model of a vapor/liquid interface, or a solid with

an irregular-shaped geometry containing void regions, or

"hybrid pair style simulations"_pair_hybrid.html which combine

pair styles with different computational cost.  In these cases, the

LAMMPS default of dividing the simulation box volume into a

regular-spaced grid of 3d bricks, with one equal-volume sub-domain

per procesor, may assign numbers of particles per processor in a

way that the computational effort varies significantly.  This can

lead to poor performance when the simulation is run in parallel.

Note that the "processors"_processors.html command allows some control

over how the box volume is split across processors.  Specifically, for

:line

The {group-ID} is currently ignored.  In the future it may be used to

determine what particles are considered for balancing.  Normally it

would only makes sense to use the {all} group.  But in some cases it

may be useful to balance on a subset of the particles, e.g. when

modeling large nanoparticles in a background of small solvent

particles.

The {group-ID} is currently ignored. Load-balancing will always affect

all atoms. However the different impact of different groups of atoms in

a simulation can be considered through the {group} keyword and assigning

different weight factors != 1.0 to atoms in these groups.

The {Nfreq} setting determines how often a rebalance is performed.  If

{Nfreq} > 0, then rebalancing will occur every {Nfreq} steps.  Each

3 = imbalance factor right before the last rebalance was performed :ul

As explained above, the imbalance factor is the ratio of the maximum

number of particles on any processor to the average number of

particles per processor.

number of particles (or total weight) on any processor to the average

number of particles (or total weight) per processor.

These quantities can be accessed by various "output

commands"_Section_howto.html#howto_15.  The scalar and vector values

[Restrictions:]

For 2d simulations, a "z" cannot appear in {dimstr} for the {shift}

style.

For 2d simulations, the {z} style cannot be used.  Nor can a "z"

appear in {dimstr} for the {shift} style.

[Related commands:]