Elaborate on choice of number of particles/batches in docs

docs/source/quickinstall.rst

@@ -91,13 +91,13 @@ can be used to access the installed packages.
 .. _Spack: https://spack.readthedocs.io/en/latest/
 .. _setup guide: https://spack.readthedocs.io/en/latest/getting_started.html
 
----------------------------------------
-Installing from Source on Ubuntu 15.04+
----------------------------------------
+--------------------------------
+Installing from Source on Ubuntu
+--------------------------------
 
 To build OpenMC from source, several :ref:`prerequisites <prerequisites>` are
-needed. If you are using Ubuntu 15.04 or higher, all prerequisites can be
-installed directly from the package manager.
+needed. If you are using Ubuntu or higher, all prerequisites can be installed
+directly from the package manager:
 
 .. code-block:: sh
 
@@ -136,8 +136,8 @@ should specify an installation directory where you have write access, e.g.
 
 The :mod:`openmc` Python package must be installed separately. The easiest way
 to install it is using `pip <https://pip.pypa.io/en/stable/>`_, which is
-included by default in Python 2.7 and Python 3.4+. From the root directory of
-the OpenMC distribution/repository, run:
+included by default in Python 3.4+. From the root directory of the OpenMC
+distribution/repository, run:
 
 .. code-block:: sh
 

docs/source/usersguide/settings.rst

@@ -54,9 +54,9 @@ If you don't specify a run mode, the default run mode is 'eigenvalue'.
 
 .. _usersguide_particles:
 
--------------------
-Number of Particles
--------------------
+------------
+Run Strategy
+------------
 
 For a fixed source simulation, the total number of source particle histories
 simulated is broken up into a number of *batches*, each corresponding to a
@@ -88,6 +88,79 @@ for accumulating tallies.
    settings.batches = 150
    settings.inactive = 5
 
+.. _usersguide_batches:
+
+Number of Batches
+-----------------
+
+In general, the stochastic uncertainty in your simulation results is directly
+related to how many total active particles are simulated (the product of the
+number of active batches, number of generations per batch, and number of
+particles). At a minimum, you should use enough active batches so that the
+central limit theorem is satisfied (about 30). Otherwise, reducing the overall
+uncertainty in your simulation by a factor of 2 will require using 4 times as
+many batches (since the standard deviation decreases as :math:`1/\sqrt{N}`).
+
+Number of Inactive Batches
+--------------------------
+
+For :math:`k` eigenvalue simulations, the source distribution is not known a
+priori. Thus, a "guess" of the source distribution is made and then iterated on,
+with the source evolving closer to the true distribution at each iteration. Once
+the source distribution has converged, it is then safe to start accumulating
+tallies. Consequently, a preset number of inactive batches are run before the
+active batches (where tallies are turned on) begin. The number of inactive
+batches necessary to reach a converged source depends on the spatial extent of
+the problem, its dominance ratio, what boundary conditions are used, and many
+other factors. For small problems, using 50--100 inactive batches is likely
+sufficient. For larger models, many hundreds of inactive batches may be
+necessary. Users are recommended to use the :ref:`Shannon entropy
+<usersguide_entropy>` diagnostic as a way of determining how many inactive
+batches are necessary.
+
+Specifying the initial source used for the very first batch is described in
+:ref:`below <usersguide_source>`. Although the initial source is arbitrary in
+the sense that any source will eventually converge to the correct distribution,
+using a source guess that is closer to the actual converged source distribution
+will translate into needing fewer inactive batches (and hence less simulation
+time).
+
+For fixed source simulations, the source distribution is known exactly, so no
+inactive batches are needed. In this case the :attr:`Settings.inactive`
+attribute can be omitted since it defaults to zero.
+
+Number of Generations per Batch
+-------------------------------
+
+The standard deviation of tally results is calculated assuming that all
+realizations (batches) are independent. However, in a :math:`k` eigenvalue
+calculation, the source sites for each batch are produced from fissions in the
+preceding batch, resulting in a correlation between successive batches. This
+correlation can result in an underprediction of the variance. That is, the
+variance reported is actually less than the true variance. To mitigate this
+effect, OpenMC allows you to group together multiple fission generations into a
+single batch for statistical purposes, rather than having each fission
+generation be a separate batch, which is the default behavior.
+
+Number of Particles per Generation
+----------------------------------
+
+There are several considerations for choosing the number of particles per
+generation. As discussed in :ref:`usersguide_batches`, the total number of
+active particles will determine the level of stochastic uncertainty in
+simulation results, so using a higher number of particles will result in less
+uncertainty. For parallel simulations that use OpenMP and/or MPI, the number of
+particles per generation should be large enough to ensure good load balancing
+between threads. For example, if you are running on a single processor with 32
+cores, each core should have at least 100 particles or so (i.e., at least 3,200
+particles per generation should be used). Using a larger number of particles per
+generation can also help reduce the cost of synchronization and communication
+between batches. For :math:`k` eigenvalue calculations, experts recommend_ at
+least 10,000 particles per generation to avoid any bias in the estimate of
+:math:`k` eigenvalue or tallies.
+
+.. _recommend: https://permalink.lanl.gov/object/tr?what=info:lanl-repo/lareport/LA-UR-09-03136
+
 .. _usersguide_source:
 
 -----------------------------
@@ -301,6 +374,8 @@ the source class when it is created:
 As with the basic custom source functionality, the custom source library
 location must be provided in the :attr:`openmc.Source.library` attribute.
 
+.. _usersguide_entropy:
+
 ---------------
 Shannon Entropy
 ---------------