From b66664cbf6a31dd8a9f9a2bb90fe9804eeaecad0 Mon Sep 17 00:00:00 2001 From: Paul Romano Date: Mon, 8 Mar 2021 08:03:31 -0600 Subject: [PATCH] Elaborate on choice of number of particles/batches in docs --- docs/source/quickinstall.rst | 14 ++--- docs/source/usersguide/settings.rst | 81 +++++++++++++++++++++++++++-- 2 files changed, 85 insertions(+), 10 deletions(-) diff --git a/docs/source/quickinstall.rst b/docs/source/quickinstall.rst index f0acf3593..726611ac5 100644 --- a/docs/source/quickinstall.rst +++ b/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 ` 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 `_, 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 diff --git a/docs/source/usersguide/settings.rst b/docs/source/usersguide/settings.rst index df22328e3..1f9636d39 100644 --- a/docs/source/usersguide/settings.rst +++ b/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 +` 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 `. 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 ---------------