Source biasing capabilities (#3460)

Co-authored-by: Paul Romano <paul.k.romano@gmail.com>

docs/source/io_formats/settings.rst

@@ -844,13 +844,18 @@ attributes/sub-elements:
       relative source strength of each mesh element or each point in the cloud.
 
     :volume_normalized:
-      For "mesh" spatial distrubtions, this optional boolean element specifies
+      For "mesh" spatial distributions, this optional boolean element specifies
       whether the vector of relative strengths should be multiplied by the mesh
       element volume. This is most common if the strengths represent a source
       per unit volume.
 
       *Default*: false
 
+    :bias:
+      For "mesh" and "cloud" spatial distributions, this optional element
+      specifies floating point values corresponding to alternative probabilities
+      for each value/component to use for biased sampling.
+
   :angle:
     An element specifying the angular distribution of source sites. This element
     has the following attributes:
@@ -883,6 +888,10 @@ attributes/sub-elements:
       are those of a univariate probability distribution (see the description in
       :ref:`univariate`).
 
+    :bias:
+      For "isotropic" angular distributions, this optional element specifies a
+      "mu-phi" angular distribution used for biased sampling.
+
   :energy:
     An element specifying the energy distribution of source sites. The necessary
     sub-elements/attributes are those of a univariate probability distribution
@@ -906,6 +915,10 @@ attributes/sub-elements:
     mesh element and follows the format for :ref:`source_element`. The number of
     ``<source>`` sub-elements should correspond to the number of mesh elements.
 
+  .. note:: Biased sampling can be applied to the spatial and energy distributions
+            of a source by using the ``<bias>`` sub-element (see
+            :ref:`univariate` for details on how to specify bias distributions).
+
   :constraints:
     This sub-element indicates the presence of constraints on sampled source
     sites (see :ref:`usersguide_source_constraints` for details). It may have
@@ -998,13 +1011,26 @@ variable and whose sub-elements/attributes are as follows:
   *Default*: histogram
 
 :pair:
-  For a "mixture" distribution, this element provides a distribution and its corresponding probability.
+  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.
+    This sub-element of a ``pair`` element provides information on the
+    corresponding univariate distribution.
+
+:bias:
+  This optional element specifies a biased distribution for importance sampling.
+  For continuous distributions, the ``bias`` element should contain another
+  univariate distribution with the same support (interval) as the parent
+  distribution. For discrete distributions, the ``bias`` element should contain
+  floating point values corresponding to alternative probabilities for each
+  value/component to be used for biased sampling.
+
+  *Default*: None
 
 ---------------------------------------
 ``<source_rejection_fraction>`` Element

docs/source/methods/variance_reduction.rst

@@ -22,12 +22,14 @@ not experience a single scoring event, even after billions of analog histories.
 Variance reduction techniques aim to either flatten the global uncertainty
 distribution, such that all regions of phase space have a fairly similar
 uncertainty, or to reduce the uncertainty in specific locations (such as a
-detector). There are two strategies available in OpenMC for variance reduction:
-the Monte Carlo MAGIC method and the FW-CADIS method. Both strategies work by
-developing a weight window mesh that can be utilized by subsequent Monte Carlo
-solves to split particles heading towards areas of lower flux densities while
-terminating particles in higher flux regions---all while maintaining a fair
-game.
+detector). There are three strategies available in OpenMC for variance
+reduction: weight windows generated via the MAGIC method or the FW-CADIS method,
+and source biasing. Both weight windowing strategies work by developing a mesh
+that can be utilized by subsequent Monte Carlo solves to split particles heading
+towards areas of lower flux densities while terminating particles in higher flux
+regions. In contrast, source biasing modifies source site sampling behavior to
+preferentially track particles more likely to reach phase space regions of
+interest.
 
 ------------
 MAGIC Method
@@ -132,3 +134,71 @@ aware of this.
     :label: variance_fom
 
     \text{FOM} = \frac{1}{\text{Time} \times \sigma^2}
+
+.. _methods_source_biasing:
+
+--------------
+Source Biasing
+--------------
+
+In contrast to the previous two methods that introduce population controls
+during transport, source biasing modifies the sampling of the external source
+distribution. The basic premise of the technique is that for each spatial,
+angular, energy, or time distribution of a source, an additional distribution
+can be specified provided that the two share a common support (set of points
+where the distribution is nonzero). Samples are then drawn from this "bias"
+distribution, which can be chosen to preferentially direct particles towards
+phase space regions of interest. In order to avoid biasing the tally results,
+however, a weight adjustment is applied to each sampled site as described below.
+
+Assume that the unbiased probability density function of a random variable
+:math:`X:x \rightarrow \mathbb{R}` is given by :math:`f(x)`, but that using the
+biased distribution :math:`g(x)` will result in a greater number of particle
+trajectories reaching some phase space region of interest. Then a sample
+:math:`x_0` may be drawn from :math:`g(x)` while maintaining a fair game,
+provided that its weight is adjusted as:
+
+.. math::
+    :label: source_bias
+
+    w = w_0 \times \frac{f(x_0)}{g(x_0)}
+
+where :math:`w_0` is the weight of an unbiased sample from :math:`f(x)`,
+typically unity.
+
+Returning now to Equation :eq:`source_bias`, the requirement for common support
+becomes evident. If :math:`\mathrm{supp} (g)` fully contains but is not
+identical to :math:`\mathrm{supp} (f)`, then some samples from :math:`g(x)` will
+correspond to points where :math:`f(x) = 0`. Thus these source sites would be
+assigned a starting weight of 0, meaning the particles would be killed
+immediately upon transport, effectively wasting computation time. Conversely, if
+:math:`\mathrm{supp} (g)` is fully contained by but not identical to
+:math:`\mathrm{supp} (f)`, the contributions of some regions outside
+:math:`\mathrm{supp} (g)` will not be counted towards the integral, potentially
+biasing the tally. The weight assigned to such points would be undefined since
+:math:`g(x) = \mathbf{0}` at these points.
+
+When an independent source is sampled in OpenMC, the particle's coordinate in
+each variable of phase space :math:`(\mathbf{r},\mathbf{\Omega},E,t)` is
+successively drawn from an independent probability distribution. Multiple
+variables can be biased, in which case the resultant weight :math:`w` applied to
+the particle is the product of the weights assigned from all sampled
+distributions: space, angle, energy, and time, as shown in Equation
+:eq:`tot_wgt`.
+
+.. math::
+    :label: tot_wgt
+
+    w = w_r \times w_{\Omega} \times w_E \times w_t
+
+Finally, source biasing and weight windows serve different purposes. Source
+biasing changes how particles are born, allowing the initial source sites to be
+sampled preferentially from important regions of phase space (space, angle,
+energy, and time) with an accompanying weight adjustment. Weight windows, by
+contrast, apply population control during transport (splitting and Russian
+roulette) to help particles reach and contribute in important regions as they
+move through the system. Because particle transport proceeds as usual after a
+biased source is sampled, particle attenuation in optically thick regions
+outside the source volume will not be affected by source biasing; in such
+scenarios, transport biasing techniques such as weight windows are often more
+effective.

docs/source/usersguide/settings.rst

@@ -272,6 +272,12 @@ option::
   settings.source = [src1, src2]
   settings.uniform_source_sampling = True
 
+Additionally, sampling from an :class:`openmc.IndependentSource` may be biased
+for local or global variance reduction by modifying the
+:attr:`~openmc.IndependentSource.bias` attribute of each of its four main
+distributions. Further discussion of source biasing can be found in
+:ref:`source_biasing`.
+
 Finally, the :attr:`IndependentSource.particle` attribute can be used to
 indicate the source should be composed of particles other than neutrons. For
 example, the following would generate a photon source::

docs/source/usersguide/variance_reduction.rst

@@ -5,10 +5,12 @@ Variance Reduction
 ==================
 
 Global variance reduction in OpenMC is accomplished by weight windowing
-techniques. OpenMC is capable of generating weight windows using either the
-MAGIC or FW-CADIS methods. Both techniques will produce a ``weight_windows.h5``
-file that can be loaded and used later on. In this section, we break down the
-steps required to both generate and then apply weight windows.
+or source biasing techniques, the latter of which additionally provides a
+local variance reduction capability. OpenMC is capable of generating weight
+windows using either the MAGIC or FW-CADIS methods. Both techniques will
+produce a ``weight_windows.h5`` file that can be loaded and used later on. In
+this section, we first break down the steps required to generate and apply
+weight windows, then describe how source biasing may be applied.
 
 .. _ww_generator:
 
@@ -172,3 +174,148 @@ Weight window mesh information is embedded into the weight window file, so the
 mesh does not need to be redefined. Monte Carlo solves that load a weight window
 file as above will utilize weight windows to reduce the variance of the
 simulation.
+
+.. _source_biasing:
+
+--------------
+Source Biasing
+--------------
+
+In fixed source problems, source biasing provides a means to reduce the variance
+on global or localized responses, depending on the biasing scheme. In either
+case, the premise of the method is to sample source sites from a biased
+distribution that directs a larger fraction of the simulated histories towards
+phase space regions of interest than would be found there under analog sampling.
+In order to preserve an unbiased estimate of the tally mean, the weight of these
+with analog sampling, divided by the probability assigned by the biased
+distribution. While the assignment of statistical weights is outlined in the
+:ref:`methods section <methods_source_biasing>`, this section demonstrates the
+implementation of source biasing to problems in OpenMC.
+
+Source biasing in OpenMC is accomplished by applying a distribution to the
+:attr:`bias` attribute of one or more of the univariate or independent
+multivariate distributions which make up an :class:`~openmc.IndependentSource`
+instance as follows::
+
+    # First create the biased distribution
+    biased_dist = openmc.stats.PowerLaw(a=0, b=3, n=3)
+
+    # Construct a new distribution with the bias applied
+    dist = openmc.stats.PowerLaw(a=0, b=3, n=2, bias=biased_dist)
+
+    # The bias attribute can also be set on an existing "analog" distribution:
+    sphere_dist = openmc.stats.spherical_uniform(r_outer=3)
+    sphere_dist.r.bias = biased_dist
+
+Univariate distributions may be sampled via the Python API, returning the
+sample(s) along with the associated weight(s)::
+
+    sample_vec, wgt_vec = dist.sample(n_samples=100)
+
+Here, if the distribution is unbiased, the weight of each sample will be unity.
+Finally, :class:`~openmc.IndependentSource` instances can be constructed with
+biased distributions::
+
+    # Create a source with a biased spatial distribution
+    source = openmc.IndependentSource(space=sphere_dist)
+
+During the simulation, source sites are then sampled using the biased
+distributions where available and given starting statistical weights
+corresponding to the cumulative product of the weights assigned by each
+distribution in the source object. Hence multiple source variables (e.g.,
+direction and energy) may be biased and the resulting source sites will have
+their weights adjusted accordingly.
+
+.. note::
+    Combining source biasing with weight windows can be a powerful variance
+    reduction technique if each is constructed appropriately for the response
+    of interest. For example, if a source biasing scheme is devised for
+    variance reduction of a specific localized response, the user may be able
+    to specify their own weight window structure that results in more efficient
+    transport than if weight windows were generated by either of OpenMC's
+    automatic weight window generators, which are intended for global variance
+    reduction.
+
+Biased distributions that could result in degenerate weight mappings are not
+recommended; this is most commonly seen when biasing the :math:`\phi`-coordinate
+of spherical or cylindrical independent multivariate distributions. In such
+cases degenerate behavior will be observed at the pole about which :math:`\phi`
+is measured, with all values of :math:`\phi` (hence many possible statistical
+weights) mapping to the same point for :math:`r=0` or :math:`\mu=0`, and large
+weight gradients in the vicinity. In most cases requiring a spherical
+independent source, it would be preferable to reorient the reference vector of
+the distribution such that biasing could be applied to the
+:math:`\mu`-coordinate instead.
+
+When biasing a distribution, care should also be taken to ensure that both the
+unbiased and biased distribution share a common support---that is, every region
+of phase space mapped to a nonzero probability density by the unbiased
+distribution should likewise map to nonzero probability under the biased
+distribution, and vice versa. In OpenMC, this places restrictions on the set of
+compatible distributions that may be used to bias sampling of each distribution
+type. The following table summarizes the method for each distribution in OpenMC
+that permits biased sampling.
+
+.. list-table:: **Distributions that support biased sampling**
+   :header-rows: 1
+   :widths: 35 65
+
+   * - Discrete Univariate PDFs
+     - Biasing Method
+   * - :class:`openmc.stats.Discrete`
+     - Apply a vector of alternative probabilities to the :attr:`bias`
+       attribute
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 65
+
+   * - Continuous Univariate PDFs
+     - Biasing Method
+   * - :class:`openmc.stats.Uniform`,
+       :class:`openmc.stats.PowerLaw`,
+       :class:`openmc.stats.Maxwell`,
+       :class:`openmc.stats.Watt`,
+       :class:`openmc.stats.Normal`,
+       :class:`openmc.stats.Tabular`
+     - Apply a second, unbiased continous univariate PDF to the :attr:`bias`
+       attribute, ensuring that the :attr:`support` attribute of each
+       distribution is the same
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 65
+
+   * - Mixed Univariate PDFs
+     - Biasing Method
+   * - :class:`openmc.stats.Mixture`
+     - May be constructed from multiple biased univariate distributions, or a
+       second, unbiased continous univariate PDF may be applied to the
+       :attr:`bias` attribute
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 65
+
+   * - Discrete Multivariate PDFs
+     - Biasing Method
+   * - :class:`openmc.stats.PointCloud`,
+       :class:`openmc.stats.MeshSpatial`
+     - Apply a vector of the new relative probabilities of each point or mesh
+       element under biased sampling to the :attr:`bias` attribute
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 65
+
+   * - Continuous Multivariate PDFs
+     - Biasing Method
+   * - :class:`openmc.stats.CartesianIndependent`,
+       :class:`openmc.stats.CylindricalIndependent`,
+       :class:`openmc.stats.SphericalIndependent`,
+       :class:`openmc.stats.PolarAzimuthal`
+     - Construct from biased univariate distributions for :attr:`x`, :attr:`y`,
+       :attr:`z`, etc.
+   * - :class:`openmc.stats.Isotropic`
+     - Apply an unbiased :class:`openmc.stats.PolarAzimuthal` to the
+       :attr:`bias` attribute