Homec4science
Diffusion lammps (lammps-icms) Browse

lammps/doc/html/balance.html
7d77aea42d30lammps-icms

Last Change
Raw File

balance.html
View Options

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>balance command &mdash; LAMMPS documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/sphinxcontrib-images/LightBox2/lightbox2/css/lightbox.css" type="text/css" />
<link rel="top" title="LAMMPS documentation" href="index.html"/>
<link rel="up" title="Commands" href="commands.html"/>
<link rel="next" title="bond_coeff command" href="bond_coeff.html"/>
<link rel="prev" title="atom_style command" href="atom_style.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="Manual.html" class="icon icon-home"> LAMMPS
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<p class="caption"><span class="caption-text">User Documentation</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">3. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">4. Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_accelerate.html">5. Accelerating LAMMPS performance</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">6. How-to discussions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_example.html">7. Example problems</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_perf.html">8. Performance &amp; scalability</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_tools.html">9. Additional tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">10. Modifying &amp; extending LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">11. Python interface to LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">12. Errors</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_history.html">13. Future and history</a></li>
</ul>
<p class="caption"><span class="caption-text">Index</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="tutorials.html">Tutorials</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="commands.html">Commands</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="angle_coeff.html">angle_coeff command</a></li>
<li class="toctree-l2"><a class="reference internal" href="angle_style.html">angle_style command</a></li>
<li class="toctree-l2"><a class="reference internal" href="atom_modify.html">atom_modify command</a></li>
<li class="toctree-l2"><a class="reference internal" href="atom_style.html">atom_style command</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">balance command</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#syntax">Syntax</a></li>
<li class="toctree-l3"><a class="reference internal" href="#examples">Examples</a></li>
<li class="toctree-l3"><a class="reference internal" href="#description">Description</a></li>
<li class="toctree-l3"><a class="reference internal" href="#restrictions">Restrictions</a></li>
<li class="toctree-l3"><a class="reference internal" href="#related-commands">Related commands</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="bond_coeff.html">bond_coeff command</a></li>
<li class="toctree-l2"><a class="reference internal" href="bond_style.html">bond_style command</a></li>
<li class="toctree-l2"><a class="reference internal" href="bond_write.html">bond_write command</a></li>
<li class="toctree-l2"><a class="reference internal" href="boundary.html">boundary command</a></li>
<li class="toctree-l2"><a class="reference internal" href="box.html">box command</a></li>
<li class="toctree-l2"><a class="reference internal" href="change_box.html">change_box command</a></li>
<li class="toctree-l2"><a class="reference internal" href="clear.html">clear command</a></li>
<li class="toctree-l2"><a class="reference internal" href="comm_modify.html">comm_modify command</a></li>
<li class="toctree-l2"><a class="reference internal" href="comm_style.html">comm_style command</a></li>
<li class="toctree-l2"><a class="reference internal" href="compute.html">compute command</a></li>
<li class="toctree-l2"><a class="reference internal" href="compute_modify.html">compute_modify command</a></li>
<li class="toctree-l2"><a class="reference internal" href="create_atoms.html">create_atoms command</a></li>
<li class="toctree-l2"><a class="reference internal" href="create_bonds.html">create_bonds command</a></li>
<li class="toctree-l2"><a class="reference internal" href="create_box.html">create_box command</a></li>
<li class="toctree-l2"><a class="reference internal" href="delete_atoms.html">delete_atoms command</a></li>
<li class="toctree-l2"><a class="reference internal" href="delete_bonds.html">delete_bonds command</a></li>
<li class="toctree-l2"><a class="reference internal" href="dielectric.html">dielectric command</a></li>
<li class="toctree-l2"><a class="reference internal" href="dihedral_coeff.html">dihedral_coeff command</a></li>
<li class="toctree-l2"><a class="reference internal" href="dihedral_style.html">dihedral_style command</a></li>
<li class="toctree-l2"><a class="reference internal" href="dimension.html">dimension command</a></li>
<li class="toctree-l2"><a class="reference internal" href="displace_atoms.html">displace_atoms command</a></li>
<li class="toctree-l2"><a class="reference internal" href="dump.html">dump command</a></li>
<li class="toctree-l2"><a class="reference internal" href="dump.html#dump-custom-vtk-command"><code class="docutils literal"><span class="pre">dump</span> <span class="pre">custom/vtk</span></code> command</a></li>
<li class="toctree-l2"><a class="reference internal" href="dump.html#dump-h5md-command"><code class="docutils literal"><span class="pre">dump</span> <span class="pre">h5md</span></code> command</a></li>
<li class="toctree-l2"><a class="reference internal" href="dump.html#dump-image-command"><code class="docutils literal"><span class="pre">dump</span> <span class="pre">image</span></code> command</a></li>
<li class="toctree-l2"><a class="reference internal" href="dump.html#dump-movie-command"><code class="docutils literal"><span class="pre">dump</span> <span class="pre">movie</span></code> command</a></li>
<li class="toctree-l2"><a class="reference internal" href="dump.html#dump-molfile-command"><code class="docutils literal"><span class="pre">dump</span> <span class="pre">molfile</span></code> command</a></li>
<li class="toctree-l2"><a class="reference internal" href="dump_custom_vtk.html">dump custom/vtk command</a></li>
<li class="toctree-l2"><a class="reference internal" href="dump_h5md.html">dump h5md command</a></li>
<li class="toctree-l2"><a class="reference internal" href="dump_image.html">dump image command</a></li>
<li class="toctree-l2"><a class="reference internal" href="dump_image.html#dump-movie-command">dump movie command</a></li>
<li class="toctree-l2"><a class="reference internal" href="dump_modify.html">dump_modify command</a></li>
<li class="toctree-l2"><a class="reference internal" href="dump_molfile.html">dump molfile command</a></li>
<li class="toctree-l2"><a class="reference internal" href="echo.html">echo command</a></li>
<li class="toctree-l2"><a class="reference internal" href="fix.html">fix command</a></li>
<li class="toctree-l2"><a class="reference internal" href="fix_modify.html">fix_modify command</a></li>
<li class="toctree-l2"><a class="reference internal" href="group.html">group command</a></li>
<li class="toctree-l2"><a class="reference internal" href="group2ndx.html">group2ndx command</a></li>
<li class="toctree-l2"><a class="reference internal" href="group2ndx.html#ndx2group-command">ndx2group command</a></li>
<li class="toctree-l2"><a class="reference internal" href="if.html">if command</a></li>
<li class="toctree-l2"><a class="reference internal" href="improper_coeff.html">improper_coeff command</a></li>
<li class="toctree-l2"><a class="reference internal" href="improper_style.html">improper_style command</a></li>
<li class="toctree-l2"><a class="reference internal" href="include.html">include command</a></li>
<li class="toctree-l2"><a class="reference internal" href="info.html">info command</a></li>
<li class="toctree-l2"><a class="reference internal" href="jump.html">jump command</a></li>
<li class="toctree-l2"><a class="reference internal" href="kspace_modify.html">kspace_modify command</a></li>
<li class="toctree-l2"><a class="reference internal" href="kspace_style.html">kspace_style command</a></li>
<li class="toctree-l2"><a class="reference internal" href="label.html">label command</a></li>
<li class="toctree-l2"><a class="reference internal" href="lattice.html">lattice command</a></li>
<li class="toctree-l2"><a class="reference internal" href="log.html">log command</a></li>
<li class="toctree-l2"><a class="reference internal" href="mass.html">mass command</a></li>
<li class="toctree-l2"><a class="reference internal" href="min_modify.html">min_modify command</a></li>
<li class="toctree-l2"><a class="reference internal" href="min_style.html">min_style command</a></li>
<li class="toctree-l2"><a class="reference internal" href="minimize.html">minimize command</a></li>
<li class="toctree-l2"><a class="reference internal" href="molecule.html">molecule command</a></li>
<li class="toctree-l2"><a class="reference internal" href="neb.html">neb command</a></li>
<li class="toctree-l2"><a class="reference internal" href="neigh_modify.html">neigh_modify command</a></li>
<li class="toctree-l2"><a class="reference internal" href="neighbor.html">neighbor command</a></li>
<li class="toctree-l2"><a class="reference internal" href="newton.html">newton command</a></li>
<li class="toctree-l2"><a class="reference internal" href="next.html">next command</a></li>
<li class="toctree-l2"><a class="reference internal" href="package.html">package command</a></li>
<li class="toctree-l2"><a class="reference internal" href="pair_coeff.html">pair_coeff command</a></li>
<li class="toctree-l2"><a class="reference internal" href="pair_modify.html">pair_modify command</a></li>
<li class="toctree-l2"><a class="reference internal" href="pair_style.html">pair_style command</a></li>
<li class="toctree-l2"><a class="reference internal" href="pair_write.html">pair_write command</a></li>
<li class="toctree-l2"><a class="reference internal" href="partition.html">partition command</a></li>
<li class="toctree-l2"><a class="reference internal" href="prd.html">prd command</a></li>
<li class="toctree-l2"><a class="reference internal" href="print.html">print command</a></li>
<li class="toctree-l2"><a class="reference internal" href="processors.html">processors command</a></li>
<li class="toctree-l2"><a class="reference internal" href="python.html">python command</a></li>
<li class="toctree-l2"><a class="reference internal" href="quit.html">quit command</a></li>
<li class="toctree-l2"><a class="reference internal" href="read_data.html">read_data command</a></li>
<li class="toctree-l2"><a class="reference internal" href="read_dump.html">read_dump command</a></li>
<li class="toctree-l2"><a class="reference internal" href="read_restart.html">read_restart command</a></li>
<li class="toctree-l2"><a class="reference internal" href="region.html">region command</a></li>
<li class="toctree-l2"><a class="reference internal" href="replicate.html">replicate command</a></li>
<li class="toctree-l2"><a class="reference internal" href="rerun.html">rerun command</a></li>
<li class="toctree-l2"><a class="reference internal" href="reset_timestep.html">reset_timestep command</a></li>
<li class="toctree-l2"><a class="reference internal" href="restart.html">restart command</a></li>
<li class="toctree-l2"><a class="reference internal" href="run.html">run command</a></li>
<li class="toctree-l2"><a class="reference internal" href="run_style.html">run_style command</a></li>
<li class="toctree-l2"><a class="reference internal" href="set.html">set command</a></li>
<li class="toctree-l2"><a class="reference internal" href="shell.html">shell command</a></li>
<li class="toctree-l2"><a class="reference internal" href="special_bonds.html">special_bonds command</a></li>
<li class="toctree-l2"><a class="reference internal" href="suffix.html">suffix command</a></li>
<li class="toctree-l2"><a class="reference internal" href="tad.html">tad command</a></li>
<li class="toctree-l2"><a class="reference internal" href="temper.html">temper command</a></li>
<li class="toctree-l2"><a class="reference internal" href="thermo.html">thermo command</a></li>
<li class="toctree-l2"><a class="reference internal" href="thermo_modify.html">thermo_modify command</a></li>
<li class="toctree-l2"><a class="reference internal" href="thermo_style.html">thermo_style command</a></li>
<li class="toctree-l2"><a class="reference internal" href="timer.html">timer command</a></li>
<li class="toctree-l2"><a class="reference internal" href="timestep.html">timestep command</a></li>
<li class="toctree-l2"><a class="reference internal" href="uncompute.html">uncompute command</a></li>
<li class="toctree-l2"><a class="reference internal" href="undump.html">undump command</a></li>
<li class="toctree-l2"><a class="reference internal" href="unfix.html">unfix command</a></li>
<li class="toctree-l2"><a class="reference internal" href="units.html">units command</a></li>
<li class="toctree-l2"><a class="reference internal" href="variable.html">variable command</a></li>
<li class="toctree-l2"><a class="reference internal" href="velocity.html">velocity command</a></li>
<li class="toctree-l2"><a class="reference internal" href="write_coeff.html">write_coeff command</a></li>
<li class="toctree-l2"><a class="reference internal" href="write_data.html">write_data command</a></li>
<li class="toctree-l2"><a class="reference internal" href="write_dump.html">write_dump command</a></li>
<li class="toctree-l2"><a class="reference internal" href="write_restart.html">write_restart command</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="fixes.html">Fixes</a></li>
<li class="toctree-l1"><a class="reference internal" href="computes.html">Computes</a></li>
<li class="toctree-l1"><a class="reference internal" href="pairs.html">Pair Styles</a></li>
<li class="toctree-l1"><a class="reference internal" href="bonds.html">Bond Styles</a></li>
<li class="toctree-l1"><a class="reference internal" href="angles.html">Angle Styles</a></li>
<li class="toctree-l1"><a class="reference internal" href="dihedrals.html">Dihedral Styles</a></li>
<li class="toctree-l1"><a class="reference internal" href="impropers.html">Improper Styles</a></li>
</ul>
</div>
&nbsp;
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="Manual.html">LAMMPS</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="Manual.html">Docs</a> &raquo;</li>
<li><a href="commands.html">Commands</a> &raquo;</li>
<li>balance command</li>
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Website</a>
<a href="Section_commands.html#comm">Commands</a>
</li>
</ul>
<hr/>
<div class="rst-footer-buttons" style="margin-bottom: 1em" role="navigation" aria-label="footer navigation">
<a href="bond_coeff.html" class="btn btn-neutral float-right" title="bond_coeff command" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="atom_style.html" class="btn btn-neutral" title="atom_style command" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="balance-command">
<span id="index-0"></span><h1>balance command</h1>
<div class="section" id="syntax">
<h2>Syntax</h2>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">balance</span> <span class="n">thresh</span> <span class="n">style</span> <span class="n">args</span> <span class="o">...</span> <span class="n">keyword</span> <span class="n">value</span> <span class="o">...</span>
</pre></div>
</div>
<ul>
<li><p class="first">thresh = imbalance threshhold that must be exceeded to perform a re-balance</p>
</li>
<li><p class="first">one style/arg pair can be used (or multiple for <em>x</em>,<em>y</em>,<em>z</em>)</p>
</li>
<li><p class="first">style = <em>x</em> or <em>y</em> or <em>z</em> or <em>shift</em> or <em>rcb</em></p>
<pre class="literal-block">
<em>x</em> args = <em>uniform</em> or Px-1 numbers between 0 and 1
<em>uniform</em> = evenly spaced cuts between processors in x dimension
numbers = Px-1 ascending values between 0 and 1, Px - # of processors in x dimension
<em>x</em> can be specified together with <em>y</em> or <em>z</em>
<em>y</em> args = <em>uniform</em> or Py-1 numbers between 0 and 1
<em>uniform</em> = evenly spaced cuts between processors in y dimension
numbers = Py-1 ascending values between 0 and 1, Py - # of processors in y dimension
<em>y</em> can be specified together with <em>x</em> or <em>z</em>
<em>z</em> args = <em>uniform</em> or Pz-1 numbers between 0 and 1
<em>uniform</em> = evenly spaced cuts between processors in z dimension
numbers = Pz-1 ascending values between 0 and 1, Pz - # of processors in z dimension
<em>z</em> can be specified together with <em>x</em> or <em>y</em>
<em>shift</em> args = dimstr Niter stopthresh
dimstr = sequence of letters containing &quot;x&quot; or &quot;y&quot; or &quot;z&quot;, each not more than once
Niter = # of times to iterate within each dimension of dimstr sequence
stopthresh = stop balancing when this imbalance threshhold is reached
<em>rcb</em> args = none
</pre>
</li>
<li><p class="first">zero or more keyword/value pairs may be appended</p>
</li>
<li><p class="first">keyword = <em>out</em></p>
<pre class="literal-block">
<em>out</em> value = filename
filename = write each processor's sub-domain to a file
</pre>
</li>
</ul>
</div>
<div class="section" id="examples">
<h2>Examples</h2>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">balance</span> <span class="mf">0.9</span> <span class="n">x</span> <span class="n">uniform</span> <span class="n">y</span> <span class="mf">0.4</span> <span class="mf">0.5</span> <span class="mf">0.6</span>
<span class="n">balance</span> <span class="mf">1.2</span> <span class="n">shift</span> <span class="n">xz</span> <span class="mi">5</span> <span class="mf">1.1</span>
<span class="n">balance</span> <span class="mf">1.0</span> <span class="n">shift</span> <span class="n">xz</span> <span class="mi">5</span> <span class="mf">1.1</span>
<span class="n">balance</span> <span class="mf">1.1</span> <span class="n">rcb</span>
<span class="n">balance</span> <span class="mf">1.0</span> <span class="n">shift</span> <span class="n">x</span> <span class="mi">20</span> <span class="mf">1.0</span> <span class="n">out</span> <span class="n">tmp</span><span class="o">.</span><span class="n">balance</span>
</pre></div>
</div>
</div>
<div class="section" id="description">
<h2>Description</h2>
<p>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 &#8220;static&#8221; 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 &#8220;dynamic&#8221; balancing, see the <a class="reference internal" href="fix_balance.html"><span class="doc">fix balance</span></a> command, which can adjust processor
sub-domain sizes and shapes on-the-fly during a <a class="reference internal" href="run.html"><span class="doc">run</span></a>.</p>
<p>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.</p>
<p>Note that the <a class="reference internal" href="processors.html"><span class="doc">processors</span></a> command allows some control
over how the box volume is split across processors. Specifically, for
a Px by Py by Pz grid of processors, it allows choice of Px, Py, and
Pz, subject to the constraint that Px * Py * Pz = P, the total number
of processors. This is sufficient to achieve good load-balance for
some problems on some processor counts. However, all the processor
sub-domains will still have the same shape and same volume.</p>
<p>The requested load-balancing operation is only performed if the
current &#8220;imbalance factor&#8221; in particles owned by each processor
exceeds the specified <em>thresh</em> parameter. The imbalance factor is
defined as the maximum number of particles owned by any processor,
divided by the average number of particles per processor. Thus an
imbalance factor of 1.0 is perfect balance.</p>
<p>As an example, for 10000 particles running on 10 processors, if the
most heavily loaded processor has 1200 particles, then the factor is
1.2, meaning there is a 20% imbalance. Note that a re-balance can be
forced even if the current balance is perfect (1.0) be specifying a
<em>thresh</em> &lt; 1.0.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Balancing is performed even if the imbalance factor does not
exceed the <em>thresh</em> parameter if a &#8220;grid&#8221; style is specified when the
current partitioning is &#8220;tiled&#8221;. The meaning of &#8220;grid&#8221; vs &#8220;tiled&#8221; is
explained below. This is to allow forcing of the partitioning to
&#8220;grid&#8221; so that the <a class="reference internal" href="comm_style.html"><span class="doc">comm_style brick</span></a> command can then
be used to replace a current <a class="reference internal" href="comm_style.html"><span class="doc">comm_style tiled</span></a>
setting.</p>
</div>
<p>When the balance command completes, it prints statistics about the
result, including the change in the imbalance factor and the change in
the maximum number of particles on any processor. For &#8220;grid&#8221; methods
(defined below) that create a logical 3d grid of processors, the
positions of all cutting planes in each of the 3 dimensions (as
fractions of the box length) are also printed.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This command attempts to minimize the imbalance factor, as
defined above. But depending on the method a perfect balance (1.0)
may not be achieved. For example, &#8220;grid&#8221; 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
the <a class="reference internal" href="create_atoms.html"><span class="doc">create_atoms</span></a> command, then &#8220;grid&#8221; methods may
be unable to achieve exact balance. This is because entire lattice
planes will be owned or not owned by a single processor.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The imbalance factor is also an estimate of the maximum speed-up
you can hope to achieve by running a perfectly balanced simulation
versus an imbalanced one. In the example above, the 10000 particle
simulation could run up to 20% faster if it were perfectly balanced,
versus when imbalanced. However, computational cost is not strictly
proportional to particle count, and changing the relative size and
shape of processor sub-domains may lead to additional computational
and communication overheads, e.g. in the PPPM solver used via the
<a class="reference internal" href="kspace_style.html"><span class="doc">kspace_style</span></a> command. Thus you should benchmark
the run times of a simulation before and after balancing.</p>
</div>
<hr class="docutils" />
<p>The method used to perform a load balance is specified by one of the
listed styles (or more in the case of <em>x</em>,<em>y</em>,<em>z</em>), which are
described in detail below. There are 2 kinds of styles.</p>
<p>The <em>x</em>, <em>y</em>, <em>z</em>, and <em>shift</em> styles are &#8220;grid&#8221; methods which produce
a logical 3d grid of processors. They operate by changing the cutting
planes (or lines) between processors in 3d (or 2d), to adjust the
volume (area in 2d) assigned to each processor, as in the following 2d
diagram where processor sub-domains are shown and atoms are colored by
the processor that owns them. The leftmost diagram is the default
partitioning of the simulation box across processors (one sub-box for
each of 16 processors); the middle diagram is after a &#8220;grid&#8221; method
has been applied.</p>
<a class=""
data-lightbox="group-default"
href="_images/balance_uniform.jpg"
title=""
data-title=""
><img src="_images/balance_uniform.jpg"
class=""
width="25%"
height="auto"
alt=""/>
</a><a class=""
data-lightbox="group-default"
href="_images/balance_nonuniform.jpg"
title=""
data-title=""
><img src="_images/balance_nonuniform.jpg"
class=""
width="25%"
height="auto"
alt=""/>
</a><a class=""
data-lightbox="group-default"
href="_images/balance_rcb.jpg"
title=""
data-title=""
><img src="_images/balance_rcb.jpg"
class=""
width="25%"
height="auto"
alt=""/>
</a><p>The <em>rcb</em> style is a &#8220;tiling&#8221; method which does not produce a logical
3d grid of processors. Rather it tiles the simulation domain with
rectangular sub-boxes of varying size and shape in an irregular
fashion so as to have equal numbers of particles in each sub-box, as
in the rightmost diagram above.</p>
<p>The &#8220;grid&#8221; methods can be used with either of the
<a class="reference internal" href="comm_style.html"><span class="doc">comm_style</span></a> command options, <em>brick</em> or <em>tiled</em>. The
&#8220;tiling&#8221; methods can only be used with <a class="reference internal" href="comm_style.html"><span class="doc">comm_style tiled</span></a>. Note that it can be useful to use a &#8220;grid&#8221;
method with <a class="reference internal" href="comm_style.html"><span class="doc">comm_style tiled</span></a> to return the domain
partitioning to a logical 3d grid of processors so that &#8220;comm_style
brick&#8221; can afterwords be specified for subsequent <a class="reference internal" href="run.html"><span class="doc">run</span></a>
commands.</p>
<p>When a &#8220;grid&#8221; method is specified, the current domain partitioning can
be either a logical 3d grid or a tiled partitioning. In the former
case, the current logical 3d grid is used as a starting point and
changes are made to improve the imbalance factor. In the latter case,
the tiled partitioning is discarded and a logical 3d grid is created
with uniform spacing in all dimensions. This becomes the starting
point for the balancing operation.</p>
<p>When a &#8220;tiling&#8221; method is specified, the current domain partitioning
(&#8220;grid&#8221; or &#8220;tiled&#8221;) is ignored, and a new partitioning is computed
from scratch.</p>
<hr class="docutils" />
<p>The <em>x</em>, <em>y</em>, and <em>z</em> styles invoke a &#8220;grid&#8221; method for balancing, as
described above. Note that any or all of these 3 styles can be
specified together, one after the other, but they cannot be used with
any other style. This style adjusts the position of cutting planes
between processor sub-domains in specific dimensions. Only the
specified dimensions are altered.</p>
<p>The <em>uniform</em> argument spaces the planes evenly, as in the left
diagrams above. The <em>numeric</em> argument requires listing Ps-1 numbers
that specify the position of the cutting planes. This requires
knowing Ps = Px or Py or Pz = the number of processors assigned by
LAMMPS to the relevant dimension. This assignment is made (and the
Px, Py, Pz values printed out) when the simulation box is created by
the &#8220;create_box&#8221; or &#8220;read_data&#8221; or &#8220;read_restart&#8221; command and is
influenced by the settings of the <a class="reference internal" href="processors.html"><span class="doc">processors</span></a>
command.</p>
<p>Each of the numeric values must be between 0 and 1, and they must be
listed in ascending order. They represent the fractional position of
the cutting place. The left (or lower) edge of the box is 0.0, and
the right (or upper) edge is 1.0. Neither of these values is
specified. Only the interior Ps-1 positions are specified. Thus is
there are 2 procesors in the x dimension, you specify a single value
such as 0.75, which would make the left processor&#8217;s sub-domain 3x
larger than the right processor&#8217;s sub-domain.</p>
<hr class="docutils" />
<p>The <em>shift</em> style invokes a &#8220;grid&#8221; method for balancing, as
described above. It changes the positions of cutting planes between
processors in an iterative fashion, seeking to reduce the imbalance
factor, similar to how the <a class="reference internal" href="fix_balance.html"><span class="doc">fix balance shift</span></a>
command operates.</p>
<p>The <em>dimstr</em> argument is a string of characters, each of which must be
an &#8220;x&#8221; or &#8220;y&#8221; or &#8220;z&#8221;. Eacn character can appear zero or one time,
since there is no advantage to balancing on a dimension more than
once. You should normally only list dimensions where you expect there
to be a density variation in the particles.</p>
<p>Balancing proceeds by adjusting the cutting planes in each of the
dimensions listed in <em>dimstr</em>, one dimension at a time. For a single
dimension, the balancing operation (described below) is iterated on up
to <em>Niter</em> times. After each dimension finishes, the imbalance factor
is re-computed, and the balancing operation halts if the <em>stopthresh</em>
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 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.</p>
<p>Once the rebalancing is complete and final processor sub-domains
assigned, particles are migrated to their new owning processor, and
the balance procedure ends.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">At each rebalance operation, the bisectioning for each cutting
plane (line in 2d) typcially starts with low and high bounds separated
by the extent of a processor&#8217;s sub-domain in one dimension. The size
of this bracketing region shrinks by 1/2 every iteration. Thus if
<em>Niter</em> is specified as 10, the cutting plane will typically be
positioned to 1 part in 1000 accuracy (relative to the perfect target
position). For <em>Niter</em> = 20, it will be accurate to 1 part in a
million. Thus there is no need ot set <em>Niter</em> to a large value.
LAMMPS will check if the threshold accuracy is reached (in a
dimension) is less iterations than <em>Niter</em> and exit early. However,
<em>Niter</em> 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>
</div>
<hr class="docutils" />
<p>The <em>rcb</em> style invokes a &#8220;tiled&#8221; method for balancing, as described
above. It performs a recursive coordinate bisectioning (RCB) of the
simulation domain. The basic idea is as follows.</p>
<p>The simulation domain is cut into 2 boxes by an axis-aligned cut in
the longest dimension, leaving one new box on either side of the cut.
All the processors are also partitioned into 2 groups, half assigned
to the box on the lower side of the cut, and half to the box on the
upper side. (If the processor count is odd, one side gets an extra
processor.) The cut is positioned so that the number of atoms in the
lower box is exactly the number that the processors assigned to that
box should own for load balance to be perfect. This also makes load
balance for the upper box perfect. The positioning is done
iteratively, by a bisectioning method. Note that counting atoms on
either side of the cut requires communication between all processors
at each iteration.</p>
<p>That is the procedure for the first cut. Subsequent cuts are made
recursively, in exactly the same manner. The subset of processors
assigned to each box make a new cut in the longest dimension of that
box, splitting the box, the subset of processsors, and the atoms in
the box in two. The recursion continues until every processor is
assigned a sub-box of the entire simulation domain, and owns the atoms
in that sub-box.</p>
<hr class="docutils" />
<p>The <em>out</em> keyword writes a text file to the specified <em>filename</em> with
the results of the balancing operation. The file contains the bounds
of the sub-domain for each processor after the balancing operation
completes. The format of the file is compatible with the
<a class="reference external" href="pizza">Pizza.py</a> <em>mdump</em> tool which has support for manipulating and
visualizing mesh files. An example is shown here for a balancing by 4
processors for a 2d problem:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">ITEM</span><span class="p">:</span> <span class="n">TIMESTEP</span>
<span class="mi">0</span>
<span class="n">ITEM</span><span class="p">:</span> <span class="n">NUMBER</span> <span class="n">OF</span> <span class="n">NODES</span>
<span class="mi">16</span>
<span class="n">ITEM</span><span class="p">:</span> <span class="n">BOX</span> <span class="n">BOUNDS</span>
<span class="mi">0</span> <span class="mi">10</span>
<span class="mi">0</span> <span class="mi">10</span>
<span class="mi">0</span> <span class="mi">10</span>
<span class="n">ITEM</span><span class="p">:</span> <span class="n">NODES</span>
<span class="mi">1</span> <span class="mi">1</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span>
<span class="mi">2</span> <span class="mi">1</span> <span class="mi">5</span> <span class="mi">0</span> <span class="mi">0</span>
<span class="mi">3</span> <span class="mi">1</span> <span class="mi">5</span> <span class="mi">5</span> <span class="mi">0</span>
<span class="mi">4</span> <span class="mi">1</span> <span class="mi">0</span> <span class="mi">5</span> <span class="mi">0</span>
<span class="mi">5</span> <span class="mi">1</span> <span class="mi">5</span> <span class="mi">0</span> <span class="mi">0</span>
<span class="mi">6</span> <span class="mi">1</span> <span class="mi">10</span> <span class="mi">0</span> <span class="mi">0</span>
<span class="mi">7</span> <span class="mi">1</span> <span class="mi">10</span> <span class="mi">5</span> <span class="mi">0</span>
<span class="mi">8</span> <span class="mi">1</span> <span class="mi">5</span> <span class="mi">5</span> <span class="mi">0</span>
<span class="mi">9</span> <span class="mi">1</span> <span class="mi">0</span> <span class="mi">5</span> <span class="mi">0</span>
<span class="mi">10</span> <span class="mi">1</span> <span class="mi">5</span> <span class="mi">5</span> <span class="mi">0</span>
<span class="mi">11</span> <span class="mi">1</span> <span class="mi">5</span> <span class="mi">10</span> <span class="mi">0</span>
<span class="mi">12</span> <span class="mi">1</span> <span class="mi">10</span> <span class="mi">5</span> <span class="mi">0</span>
<span class="mi">13</span> <span class="mi">1</span> <span class="mi">5</span> <span class="mi">5</span> <span class="mi">0</span>
<span class="mi">14</span> <span class="mi">1</span> <span class="mi">10</span> <span class="mi">5</span> <span class="mi">0</span>
<span class="mi">15</span> <span class="mi">1</span> <span class="mi">10</span> <span class="mi">10</span> <span class="mi">0</span>
<span class="mi">16</span> <span class="mi">1</span> <span class="mi">5</span> <span class="mi">10</span> <span class="mi">0</span>
<span class="n">ITEM</span><span class="p">:</span> <span class="n">TIMESTEP</span>
<span class="mi">0</span>
<span class="n">ITEM</span><span class="p">:</span> <span class="n">NUMBER</span> <span class="n">OF</span> <span class="n">SQUARES</span>
<span class="mi">4</span>
<span class="n">ITEM</span><span class="p">:</span> <span class="n">SQUARES</span>
<span class="mi">1</span> <span class="mi">1</span> <span class="mi">1</span> <span class="mi">2</span> <span class="mi">3</span> <span class="mi">4</span>
<span class="mi">2</span> <span class="mi">1</span> <span class="mi">5</span> <span class="mi">6</span> <span class="mi">7</span> <span class="mi">8</span>
<span class="mi">3</span> <span class="mi">1</span> <span class="mi">9</span> <span class="mi">10</span> <span class="mi">11</span> <span class="mi">12</span>
<span class="mi">4</span> <span class="mi">1</span> <span class="mi">13</span> <span class="mi">14</span> <span class="mi">15</span> <span class="mi">16</span>
</pre></div>
</div>
<p>The coordinates of all the vertices are listed in the NODES section, 5
per processor. Note that the 4 sub-domains share vertices, so there
will be duplicate nodes in the list.</p>
<p>The &#8220;SQUARES&#8221; section lists the node IDs of the 4 vertices in a
rectangle for each processor (1 to 4).</p>
<p>For a 3d problem, the syntax is similar with 8 vertices listed for
each processor, instead of 4, and &#8220;SQUARES&#8221; replaced by &#8220;CUBES&#8221;.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions</h2>
<p>For 2d simulations, the <em>z</em> style cannot be used. Nor can a &#8220;z&#8221;
appear in <em>dimstr</em> for the <em>shift</em> style.</p>
</div>
<div class="section" id="related-commands">
<h2>Related commands</h2>
<p><a class="reference internal" href="processors.html"><span class="doc">processors</span></a>, <a class="reference internal" href="fix_balance.html"><span class="doc">fix balance</span></a></p>
<p><strong>Default:</strong> none</p>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="bond_coeff.html" class="btn btn-neutral float-right" title="bond_coeff command" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="atom_style.html" class="btn btn-neutral" title="atom_style command" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2013 Sandia Corporation.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/lightbox.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2-customize/jquery-noconflict.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
c4science · Help