Loading doc/README +46 −3 Original line number Diff line number Diff line Generation of LAMMPS Documentation LAMMPS Documentation Depending on how you obtained LAMMPS, this directory has 2 or 3 sub-directories and optionally 2 PDF files: src content files for LAMMPS documentation html HTML version of the LAMMPS manual (see html/Manual.html) tools tools and settings for building the documentation Manual.pdf large PDF version of entire manual Developer.pdf small PDF with info about how LAMMPS is structured If you downloaded LAMMPS as a tarball from the web site, all these directories and files should be included. If you downloaded LAMMPS from the public SVN or Git repositories, then the HTML and PDF files are not included. Instead you need to create them, in one of three ways: (a) You can "fetch" the current HTML and PDF files from the LAMMPS web site. Just type "make fetch". This should create a html_www dir and Manual_www.pdf/Developer_www.pdf files. Note that if new LAMMPS features have been added more recently than the date of your version, the fetched documentation will include those changes (but your source code will not, unless you update your local repository). (b) You can build the HTML and PDF files yourself, by typing "make html" followed by "make pdf". Note that the PDF make requires the HTML files already exist. This requires various tools including Sphinx, which the build process will attempt to download and install on your system, if not already available. See more details below. (c) You can genererate an older, simpler, less-fancy style of HTML documentation by typing "make old". This will create an "old" directory. This can be useful if (b) does not work on your box for some reason, or you want to quickly view the HTML version of a doc page you have created or edited yourself within the src directory. E.g. if you are planning to submit a new feature to LAMMPS. ---------------- The generation of all documentation is managed by the Makefile in this dir. ---------------- Options: make html # generate HTML in html dir using Sphinx Loading Loading @@ -51,3 +87,10 @@ Once Python 3 is installed, open a Terminal and type pip3 install virtualenv This will install virtualenv from the Python Package Index. ---------------- Installing prerequisites for PDF build doc/src/Manual.txt +2 −2 Original line number Diff line number Diff line <!-- HTML_ONLY --> <HEAD> <TITLE>LAMMPS Users Manual</TITLE> <META NAME="docnumber" CONTENT="26 Sep 2016 version"> <META NAME="docnumber" CONTENT="28 Sep 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> Loading @@ -21,7 +21,7 @@ <H1></H1> LAMMPS Documentation :c,h3 26 Sep 2016 version :c,h4 28 Sep 2016 version :c,h4 Version info: :h4 Loading doc/src/Section_howto.txt +1 −1 Original line number Diff line number Diff line Loading @@ -2123,7 +2123,7 @@ thermo_style custom step temp press v_pxy v_pxz v_pyz v_v11 v_v22 v_v33 run 100000 variable v equal (v_v11+v_v22+v_v33)/3.0 variable ndens equal count(all)/vol print "average viscosity: $v \[Pa.s/] @ $T K, $\{ndens\} /A^3" :pre print "average viscosity: $v \[Pa.s\] @ $T K, $\{ndens\} /A^3" :pre The fifth method is related to the above Green-Kubo method, but uses the Einstein formulation, analogous to the Einstein Loading doc/src/Section_packages.txt +1 −1 Original line number Diff line number Diff line Loading @@ -845,7 +845,7 @@ PYTHON package :link(PYTHON),h5 Contents: A "python"_python.html command which allow you to execute Python code from a LAMMPS input script. The code can be in a separate file or embedded in the input script itself. See "Section 11.2"_Section_python.html#py-2 for an overview of using Python from 11.2"_Section_python.html#py_2 for an overview of using Python from LAMMPS and for other ways to use LAMMPS and Python together. Building with the PYTHON package assumes you have a Python shared Loading doc/src/balance.txt +178 −41 Original line number Diff line number Diff line Loading @@ -10,7 +10,7 @@ balance command :h3 [Syntax:] balance thresh style args ... keyword value ... :pre balance thresh style args ... keyword args ... :pre thresh = imbalance threshhold that must be exceeded to perform a re-balance :ulb,l one style/arg pair can be used (or multiple for {x},{y},{z}) :l Loading @@ -32,9 +32,23 @@ style = {x} or {y} or {z} or {shift} or {rcb} :l Niter = # of times to iterate within each dimension of dimstr sequence 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 {out} value = filename zero or more keyword/arg pairs may be appended :l keyword = {weight} or {out} :l {weight} style args = use weighted particle counts for the balancing {style} = {group} or {neigh} or {time} or {var} or {store} {group} args = Ngroup group1 weight1 group2 weight2 ... Ngroup = number of groups with assigned weights group1, group2, ... = group IDs weight1, weight2, ... = corresponding weight factors {neigh} factor = compute weight based on number of neighbors factor = scaling factor (> 0) {time} factor = compute weight based on time spend computing factor = scaling factor (> 0) {var} name = take weight from atom-style variable name = name of the atom-style variable {store} name = store weight in custom atom property defined by "fix property/atom"_fix_property_atom.html command name = atom property name (without d_ prefix) {out} arg = filename filename = write each processor's sub-domain to a file :pre :ule Loading @@ -44,28 +58,42 @@ balance 0.9 x uniform y 0.4 0.5 0.6 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 weight group 2 fast 0.5 slow 2.0 balance 1.0 shift x 10 1.1 weight time 0.8 weight neigh 0.5 weight store balance 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. The processor sub-domains will then remain static during the subsequent run. To perform "dynamic" balancing, see the "fix within the simulation box, to attempt to balance the number of atoms or 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. 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 Load-balancing is typically most useful if the particles in the simulation box have a spatially-varying density distribution or when the computational cost varies signficantly between different particles. 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 very different numbers of particles per processor. This can lead to poor performance when the simulation is run in parallel. 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. The balancing can be performed with or without per-particle weighting. With no weighting, the balancing attempts to assign an equal number of particles to each processor. With weighting, the balancing attempts to assign an equal aggregate computational weight to each processor, which typically inducces a diffrent number of atoms assigned to each processor. Details on the various weighting options and examples for how they can be used 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 Loading @@ -78,9 +106,9 @@ sub-domains will still have the same shape and same volume. The requested load-balancing operation is only performed if the current "imbalance factor" in particles owned by each processor exceeds the specified {thresh} 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. defined as the maximum number of particles (or weight) owned by any processor, divided by the average number of particles (or weight) per processor. Thus an imbalance factor of 1.0 is perfect balance. As an example, for 10000 particles running on 10 processors, if the most heavily loaded processor has 1200 particles, then the factor is Loading Loading @@ -108,7 +136,7 @@ defined above. But depending on the method a perfect balance (1.0) 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. Loading @@ -134,11 +162,11 @@ The {x}, {y}, {z}, and {shift} styles are "grid" 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 "grid" method has been applied. diagram where processor sub-domains are shown and particles 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 "grid" method has been applied. :image(JPG/balance_uniform_small.jpg,JPG/balance_uniform.jpg),image(JPG/balance_nonuniform_small.jpg,JPG/balance_nonuniform.jpg),image(JPG/balance_rcb_small.jpg,JPG/balance_rcb.jpg) :c Loading @@ -146,8 +174,8 @@ has been applied. The {rcb} style is a "tiling" 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. fashion so as to have equal numbers of particles (or weight) in each sub-box, as in the rightmost diagram above. The "grid" methods can be used with either of the "comm_style"_comm_style.html command options, {brick} or {tiled}. The Loading Loading @@ -230,7 +258,7 @@ 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 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 Loading Loading @@ -262,21 +290,129 @@ 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. processor.) The cut is positioned so that the number of particles 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 particles on either side of the cut requires communication between all processors at each iteration. 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. box, splitting the box, the subset of processsors, and the particles in the box in two. The recursion continues until every processor is assigned a sub-box of the entire simulation domain, and owns the particles in that sub-box. :line This sub-section describes how to perform weighted load balancing using the {weight} keyword. :link(weighted_balance) By default, all particles have a weight of 1.0, which means each particle is assumed to require the same amount of computation during a timestep. There are, however, scenarios where this is not a good assumption. Measuring the computational cost for each particle 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. 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 induce 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"_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 not changed. If it belongs to multiple groups, its weight is the product of the weight factors. This weight style is useful in combination with pair style "hybrid"_pair_hybrid.html, e.g. when combining a more costly manybody potential with a fast pair-wise potential. It is also useful when using "run_style respa"_run_style.html where some portions of the system have many bonded interactions and others none. It assumes that 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. 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 particles are in the vicinity of a wall, or a combination of these effects. If a simulation uses multiple neighbor lists, this weight style will use the first suitable neighbor list it finds. It will not request or compute a new list. A warning will be issued if there is no suitable 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, in which case the neighbor list may not yet have been built. In this case no 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 {var} weight style assigns per-particle weights by evaluating an "atom-style variable"_variable.html specified by {name}. This is provided as a more flexible alternative to the {group} weight style, allowing definition of a more complex heuristics based on information (global and per atom) available inside of LAMMPS. For example, atom-style variables can reference the position of a particle, its velocity, the volume of its 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, debug, or visualize the per-particle weights computed during the load-balancing operation. :line Loading Loading @@ -342,6 +478,7 @@ appear in {dimstr} for the {shift} style. [Related commands:] "processors"_processors.html, "fix balance"_fix_balance.html "group"_group.html, "processors"_processors.html, "fix balance"_fix_balance.html [Default:] none Loading
doc/README +46 −3 Original line number Diff line number Diff line Generation of LAMMPS Documentation LAMMPS Documentation Depending on how you obtained LAMMPS, this directory has 2 or 3 sub-directories and optionally 2 PDF files: src content files for LAMMPS documentation html HTML version of the LAMMPS manual (see html/Manual.html) tools tools and settings for building the documentation Manual.pdf large PDF version of entire manual Developer.pdf small PDF with info about how LAMMPS is structured If you downloaded LAMMPS as a tarball from the web site, all these directories and files should be included. If you downloaded LAMMPS from the public SVN or Git repositories, then the HTML and PDF files are not included. Instead you need to create them, in one of three ways: (a) You can "fetch" the current HTML and PDF files from the LAMMPS web site. Just type "make fetch". This should create a html_www dir and Manual_www.pdf/Developer_www.pdf files. Note that if new LAMMPS features have been added more recently than the date of your version, the fetched documentation will include those changes (but your source code will not, unless you update your local repository). (b) You can build the HTML and PDF files yourself, by typing "make html" followed by "make pdf". Note that the PDF make requires the HTML files already exist. This requires various tools including Sphinx, which the build process will attempt to download and install on your system, if not already available. See more details below. (c) You can genererate an older, simpler, less-fancy style of HTML documentation by typing "make old". This will create an "old" directory. This can be useful if (b) does not work on your box for some reason, or you want to quickly view the HTML version of a doc page you have created or edited yourself within the src directory. E.g. if you are planning to submit a new feature to LAMMPS. ---------------- The generation of all documentation is managed by the Makefile in this dir. ---------------- Options: make html # generate HTML in html dir using Sphinx Loading Loading @@ -51,3 +87,10 @@ Once Python 3 is installed, open a Terminal and type pip3 install virtualenv This will install virtualenv from the Python Package Index. ---------------- Installing prerequisites for PDF build
doc/src/Manual.txt +2 −2 Original line number Diff line number Diff line <!-- HTML_ONLY --> <HEAD> <TITLE>LAMMPS Users Manual</TITLE> <META NAME="docnumber" CONTENT="26 Sep 2016 version"> <META NAME="docnumber" CONTENT="28 Sep 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> Loading @@ -21,7 +21,7 @@ <H1></H1> LAMMPS Documentation :c,h3 26 Sep 2016 version :c,h4 28 Sep 2016 version :c,h4 Version info: :h4 Loading
doc/src/Section_howto.txt +1 −1 Original line number Diff line number Diff line Loading @@ -2123,7 +2123,7 @@ thermo_style custom step temp press v_pxy v_pxz v_pyz v_v11 v_v22 v_v33 run 100000 variable v equal (v_v11+v_v22+v_v33)/3.0 variable ndens equal count(all)/vol print "average viscosity: $v \[Pa.s/] @ $T K, $\{ndens\} /A^3" :pre print "average viscosity: $v \[Pa.s\] @ $T K, $\{ndens\} /A^3" :pre The fifth method is related to the above Green-Kubo method, but uses the Einstein formulation, analogous to the Einstein Loading
doc/src/Section_packages.txt +1 −1 Original line number Diff line number Diff line Loading @@ -845,7 +845,7 @@ PYTHON package :link(PYTHON),h5 Contents: A "python"_python.html command which allow you to execute Python code from a LAMMPS input script. The code can be in a separate file or embedded in the input script itself. See "Section 11.2"_Section_python.html#py-2 for an overview of using Python from 11.2"_Section_python.html#py_2 for an overview of using Python from LAMMPS and for other ways to use LAMMPS and Python together. Building with the PYTHON package assumes you have a Python shared Loading
doc/src/balance.txt +178 −41 Original line number Diff line number Diff line Loading @@ -10,7 +10,7 @@ balance command :h3 [Syntax:] balance thresh style args ... keyword value ... :pre balance thresh style args ... keyword args ... :pre thresh = imbalance threshhold that must be exceeded to perform a re-balance :ulb,l one style/arg pair can be used (or multiple for {x},{y},{z}) :l Loading @@ -32,9 +32,23 @@ style = {x} or {y} or {z} or {shift} or {rcb} :l Niter = # of times to iterate within each dimension of dimstr sequence 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 {out} value = filename zero or more keyword/arg pairs may be appended :l keyword = {weight} or {out} :l {weight} style args = use weighted particle counts for the balancing {style} = {group} or {neigh} or {time} or {var} or {store} {group} args = Ngroup group1 weight1 group2 weight2 ... Ngroup = number of groups with assigned weights group1, group2, ... = group IDs weight1, weight2, ... = corresponding weight factors {neigh} factor = compute weight based on number of neighbors factor = scaling factor (> 0) {time} factor = compute weight based on time spend computing factor = scaling factor (> 0) {var} name = take weight from atom-style variable name = name of the atom-style variable {store} name = store weight in custom atom property defined by "fix property/atom"_fix_property_atom.html command name = atom property name (without d_ prefix) {out} arg = filename filename = write each processor's sub-domain to a file :pre :ule Loading @@ -44,28 +58,42 @@ balance 0.9 x uniform y 0.4 0.5 0.6 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 weight group 2 fast 0.5 slow 2.0 balance 1.0 shift x 10 1.1 weight time 0.8 weight neigh 0.5 weight store balance 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. The processor sub-domains will then remain static during the subsequent run. To perform "dynamic" balancing, see the "fix within the simulation box, to attempt to balance the number of atoms or 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. 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 Load-balancing is typically most useful if the particles in the simulation box have a spatially-varying density distribution or when the computational cost varies signficantly between different particles. 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 very different numbers of particles per processor. This can lead to poor performance when the simulation is run in parallel. 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. The balancing can be performed with or without per-particle weighting. With no weighting, the balancing attempts to assign an equal number of particles to each processor. With weighting, the balancing attempts to assign an equal aggregate computational weight to each processor, which typically inducces a diffrent number of atoms assigned to each processor. Details on the various weighting options and examples for how they can be used 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 Loading @@ -78,9 +106,9 @@ sub-domains will still have the same shape and same volume. The requested load-balancing operation is only performed if the current "imbalance factor" in particles owned by each processor exceeds the specified {thresh} 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. defined as the maximum number of particles (or weight) owned by any processor, divided by the average number of particles (or weight) per processor. Thus an imbalance factor of 1.0 is perfect balance. As an example, for 10000 particles running on 10 processors, if the most heavily loaded processor has 1200 particles, then the factor is Loading Loading @@ -108,7 +136,7 @@ defined above. But depending on the method a perfect balance (1.0) 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. Loading @@ -134,11 +162,11 @@ The {x}, {y}, {z}, and {shift} styles are "grid" 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 "grid" method has been applied. diagram where processor sub-domains are shown and particles 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 "grid" method has been applied. :image(JPG/balance_uniform_small.jpg,JPG/balance_uniform.jpg),image(JPG/balance_nonuniform_small.jpg,JPG/balance_nonuniform.jpg),image(JPG/balance_rcb_small.jpg,JPG/balance_rcb.jpg) :c Loading @@ -146,8 +174,8 @@ has been applied. The {rcb} style is a "tiling" 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. fashion so as to have equal numbers of particles (or weight) in each sub-box, as in the rightmost diagram above. The "grid" methods can be used with either of the "comm_style"_comm_style.html command options, {brick} or {tiled}. The Loading Loading @@ -230,7 +258,7 @@ 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 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 Loading Loading @@ -262,21 +290,129 @@ 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. processor.) The cut is positioned so that the number of particles 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 particles on either side of the cut requires communication between all processors at each iteration. 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. box, splitting the box, the subset of processsors, and the particles in the box in two. The recursion continues until every processor is assigned a sub-box of the entire simulation domain, and owns the particles in that sub-box. :line This sub-section describes how to perform weighted load balancing using the {weight} keyword. :link(weighted_balance) By default, all particles have a weight of 1.0, which means each particle is assumed to require the same amount of computation during a timestep. There are, however, scenarios where this is not a good assumption. Measuring the computational cost for each particle 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. 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 induce 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"_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 not changed. If it belongs to multiple groups, its weight is the product of the weight factors. This weight style is useful in combination with pair style "hybrid"_pair_hybrid.html, e.g. when combining a more costly manybody potential with a fast pair-wise potential. It is also useful when using "run_style respa"_run_style.html where some portions of the system have many bonded interactions and others none. It assumes that 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. 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 particles are in the vicinity of a wall, or a combination of these effects. If a simulation uses multiple neighbor lists, this weight style will use the first suitable neighbor list it finds. It will not request or compute a new list. A warning will be issued if there is no suitable 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, in which case the neighbor list may not yet have been built. In this case no 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 {var} weight style assigns per-particle weights by evaluating an "atom-style variable"_variable.html specified by {name}. This is provided as a more flexible alternative to the {group} weight style, allowing definition of a more complex heuristics based on information (global and per atom) available inside of LAMMPS. For example, atom-style variables can reference the position of a particle, its velocity, the volume of its 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, debug, or visualize the per-particle weights computed during the load-balancing operation. :line Loading Loading @@ -342,6 +478,7 @@ appear in {dimstr} for the {shift} style. [Related commands:] "processors"_processors.html, "fix balance"_fix_balance.html "group"_group.html, "processors"_processors.html, "fix balance"_fix_balance.html [Default:] none
