Merge pull request #1947 from pshriwise/ww-final-tests

Weight windows final push

docs/source/io_formats/settings.rst

@@ -620,9 +620,9 @@ variable and whose sub-elements/attributes are as follows:
 :type:
   The type of the distribution. Valid options are "uniform", "discrete",
   "tabular", "maxwell", "watt", and "mixture". The "uniform" option produces
-  variates sampled from a uniform distribution over a finite interval. The 
-  "discrete" option produces random variates that can assume a finite number 
-  of values (i.e., a distribution characterized by a probability mass function). 
+  variates sampled from a uniform distribution over a finite interval. The
+  "discrete" option produces random variates that can assume a finite number
+  of values (i.e., a distribution characterized by a probability mass function).
   The "tabular" option produces random variates sampled from a tabulated
   distribution where the density function is either a histogram or
   linearly-interpolated between tabulated points. The "watt" option produces
@@ -668,8 +668,8 @@ variable and whose sub-elements/attributes are as follows:
   For a "mixture" distribution, this element provides a distribution and its corresponding probability.
 
   :probability:
-    An attribute or ``pair`` that provides the probability of a univariate distribution within a "mixture" distribution. 
-      
+    An attribute or ``pair`` that provides the probability of a univariate distribution within a "mixture" distribution.
+
   :dist:
     This sub-element of a ``pair`` element provides information on the corresponding univariate distribution.
 
@@ -1007,3 +1007,55 @@ sub-elements/attributes:
      sample points within.
 
      *Default*: None
+
+----------------------------
+``<weight_windows>`` Element
+----------------------------
+
+The ``<weight_windows>`` element specifies all necessary parameters for
+mesh-based weight windows. This element has the following
+sub-elements/attributes:
+
+  :id:
+    A unique integer that is used to identify the weight windows
+
+  :mesh:
+    ID of a mesh that is to be used for weight windows
+
+    *Default*: None
+
+  :particle_type:
+    The particle that the weight windows will apply to (e.g., 'neutron')
+
+    *Default*: None
+
+  :energy_bins:
+    Monotonically increasing list of bounding energies in [eV] to be used for
+    weight windows
+
+    *Default*: None
+
+  :lower_ww_bounds:
+    Lower weight window bound for each (energy bin, mesh bin) combination.
+
+    *Default*: None
+
+  :upper_ww_bounds:
+    Upper weight window bound for each (energy bin, mesh bin) combination.
+
+    *Default*: None
+
+  :survival:
+    The ratio of survival weight and lower weight window bound.
+
+    *Default*: 3.0
+
+  :max_split:
+    Maximum allowable number of particles when splitting
+
+    *Default*: 10
+
+  :weight_cutoff:
+    Threshold below which particles will be terminated
+
+    *Default*: :math:`10^{-38}`

docs/source/methods/neutron_physics.rst

@@ -1627,6 +1627,8 @@ cross sections.
 Variance Reduction Techniques
 -----------------------------
 
+.. _survival_biasing:
+
 Survival Biasing
 ----------------
 
@@ -1677,6 +1679,47 @@ default, the cutoff weight in OpenMC is :math:`w_c = 0.25` and the survival
 weight is :math:`w_s = 1.0`. These parameters vary from one Monte Carlo code to
 another.
 
+Weight Windows
+--------------
+
+In fixed source problems, it can often be difficult to obtain sufficiently low
+variance on tallies in regions that are far from the source. The `weight window
+method <https://doi.org/10.13182/FST84-A23082>`_ was developed to increase the
+population of particles in important spatial regions and energy ranges by
+controlling particle weights. Each spatial region and particle energy range is
+assigned upper and lower weight bounds, :math:`w_u` and :math:`w_\ell`,
+respectively. When a particle is in a given spatial region / energy range, its
+weight, :math:`w`, is compared to the lower and upper bounds. If the weight of
+the particle is above the upper weight bound, the particle is split into
+:math:`N` particles, where
+
+.. math::
+    :label: ww-split
+
+    N = \min(N_{max}, \lceil w/w_u \rceil)
+
+and :math:`N_{max}` is a user-defined maximum number of splits. To ensure a
+fair game, each of the :math:`N` particles is assigned a weight :math:`w/N`. If
+the weight is below :math:`w_\ell`, it is Russian rouletted as described in
+:ref:`survival_biasing` with a survival weight :math:`w_s` that is set equal to
+
+.. math::
+    :label: ww-survival-weight
+
+    w_s = \min(N_{max} w, f_s w_l)
+
+where :math:`f_s` is a user-defined survival weight ratio greater than one.
+
+On top of the standard weight window method described above, OpenMC implements
+two additional checks intended to mitigate problems with long histories. First,
+particles with a weight that falls below some very small cutoff (defaults to
+:math:`10^{-38}`) are killed with no Russian rouletting. Additionally, the total
+number of splits experienced by a particle is tracked and if it reaches some
+maximum value, it is prohibited from splitting further.
+
+At present, OpenMC allows weight windows to be defined on all supported mesh
+types.
+
 .. only:: html
 
    .. rubric:: References

docs/source/pythonapi/base.rst

@@ -24,6 +24,7 @@ Simulation Settings
    openmc.Source
    openmc.SourceParticle
    openmc.VolumeCalculation
+   openmc.WeightWindows
    openmc.Settings
 
 The following function can be used for generating a source file: