Add docs

doc/src/dump_modify.rst

@@ -17,13 +17,14 @@ Syntax
 * one or more keyword/value pairs may be appended
 
 * these keywords apply to various dump styles
-* keyword = *append* or *at* or *buffer* or *delay* or *element* or *every* or *every/time* or *fileper* or *first* or *flush* or *format* or *header* or *image* or *label* or *maxfiles* or *nfile* or *pad* or *pbc* or *precision* or *region* or *refresh* or *scale* or *sfactor* or *sort* or *tfactor* or *thermo* or *thresh* or *time* or *units* or *unwrap*
+* keyword = *append* or *at* or *balance* or *buffer* or *delay* or *element* or *every* or *every/time* or *fileper* or *first* or *flush* or *format* or *header* or *image* or *label* or *maxfiles* or *nfile* or *pad* or *pbc* or *precision* or *region* or *refresh* or *scale* or *sfactor* or *sort* or *tfactor* or *thermo* or *thresh* or *time* or *units* or *unwrap*
 
   .. parsed-literal::
 
        *append* arg = *yes* or *no*
        *at* arg = N
          N = index of frame written upon first dump
+       *balance* arg = *yes* or *no*
        *buffer* arg = *yes* or *no*
        *delay* arg = Dstep
          Dstep = delay output until this timestep
@@ -658,6 +659,13 @@ atom ID.  A sort value of N or -N means sort the output by the value
 in the Nth column of per-atom info in either ascending or descending
 order.
 
+In a parallel run, the per-processor dump file pieces can have
+significant imbalance in number of lines of per-atom info. The *balance*
+keyword determines whether lines of per-atom output for each processor
+snapshot in a parallel run are balanced to be nearly the same. A balance
+value of *no* means no balancing will be done, while *yes* means
+balancing will be performed. For a serial run, this option is ignored.
+
 The dump *local* style cannot be sorted by atom ID, since there are
 typically multiple lines of output per atom.  Some dump styles, such
 as *dcd* and *xtc*, require sorting by atom ID to format the output
@@ -832,6 +840,7 @@ Default
 The option defaults are
 
 * append = no
+* balance = no
 * buffer = yes for dump styles *atom*, *custom*, *loca*, and *xyz*
 * element = "C" for every atom type
 * every = whatever it was set to via the :doc:`dump <dump>` command

src/dump.cpp

@@ -1270,6 +1270,7 @@ void Dump::modify_params(int narg, char **arg)
 
     } else if (strcmp(arg[iarg],"balance") == 0) {
       if (iarg+2 > narg) error->all(FLERR,"Illegal dump_modify command");
+      if (nprocs > 1)
         balance_flag = utils::logical(FLERR,arg[iarg+1],false,lmp);
       iarg += 2;