Merge branch 'develop' into Sensitivity-Analysis

Author: Ebiwonjumi

CMakeLists.txt

@@ -414,7 +414,8 @@ list(APPEND libopenmc_SOURCES
   src/tallies/filter_material.cpp
   src/tallies/filter_materialfrom.cpp
   src/tallies/filter_mesh.cpp
-  src/tallies/filter_meshborn.cpp  
+  src/tallies/filter_meshborn.cpp
+  src/tallies/filter_meshmaterial.cpp
   src/tallies/filter_meshsurface.cpp
   src/tallies/filter_mu.cpp
   src/tallies/filter_musurface.cpp

docs/source/methods/energy_deposition.rst

@@ -25,19 +25,38 @@ KERMA (Kinetic Energy Release in Materials) [Mack97]_ coefficients for reaction
 :math:`\times` cross-section (e.g., eV-barn) and can be used much like a reaction
 cross section for the purpose of tallying energy deposition.
 
-KERMA coefficients can be computed using the energy-balance method with
-a nuclear data processing code like NJOY, which performs the following
-iteration over all reactions :math:`r` for all isotopes :math:`i`
-requested
+KERMA coefficients can be computed using the energy-balance method with a
+nuclear data processing code like NJOY, which estimates the KERMA coefficients
+using the following equation:
 
 .. math::
 
-    k_{i, r}(E) = \left(E + Q_{i, r} - \bar{E}_{i, r, n}
+    k_{i, r}(E) = \left(E + Q_{i, r} - \sum\limits_x \bar{E}_{i, r, x}
+    \right)\sigma_{i, r}(E),
+
+where the summation is over each secondary particle type :math:`x`. This
+equation states that the energy deposited is equal to the energy of the incident
+particle plus the reaction :math:`Q` value less the energy of secondary
+particles that are transported away from the reaction site. For neutron
+interactions, the energy-balance KERMA coefficient is
+
+.. math::
+
+    k_{i, r}(E) = \left(E + Q_{i, r} - \sum\limits_x \bar{E}_{i, r, n}
     - \bar{E}_{i, r, \gamma}\right)\sigma_{i, r}(E),
 
-removing the energy of neutral particles (neutrons and photons) that are
-transported away from the reaction site :math:`\bar{E}`, and the reaction
-:math:`Q` value.
+where :math:`\bar{E}_{i, r, n}` is the average energy of secondary neutrons and
+:math:`\bar{E}_{i, r, \gamma}` is the average energy of secondary photons. For
+photon and charged particle interactions the KERMA coefficient is
+
+.. math::
+    :label: energy-balance-photon
+
+    k_{i, r}(E) = \left(E + Q_{i, r} - \sum\limits_x \bar{E}_{i, r, x}
+    \right)\sigma_{i, r}(E).
+
+where the :math:`Q` value is zero for all interactions except for pair
+production and positron annihilation.
 
 -------
 Fission
@@ -120,7 +139,7 @@ run with :math:`N918` reflecting fission heating computed from NJOY.
 This modified heating data is stored as the MT=901 reaction and will be scored
 if ``heating-local`` is included in :attr:`openmc.Tally.scores`.
 
-Coupled neutron-photon transport
+Coupled Neutron-Photon Transport
 --------------------------------
 
 Here, OpenMC instructs ``heatr`` to assume that energy from photons is not
@@ -138,6 +157,50 @@ Let :math:`N301` represent the total heating number returned from this
 This modified heating data is stored as the MT=301 reaction and will be scored
 if ``heating`` is included in :attr:`openmc.Tally.scores`.
 
+Photons and Charged Particles
+-----------------------------
+
+In OpenMC, energy deposition from photons or charged particles is scored using
+the energy balance method based on Equation :eq:`energy-balance-photon`. Special
+consideration is given to electrons and positrons as described below.
+
++++++++++++++++++
+Charged Particles
++++++++++++++++++
+
+OpenMC tracks photons interaction by interaction so the energy deposited in each
+collision is easily attributed back to the nuclide and reaction for which the
+photon interacted with. Charged particles (electrons and photons) aren't tracked
+in the same way. For charged particles, OpenMC assumes that all their energy
+(less the energy of bremsstrahlung radiation) is deposited in the material in
+which they were born. In this way it is harder to trace how much energy should
+be attributed in each nuclide.
+
+According to the CSDA approximation (see :ref:`ttb`) the energy deposited by a
+charged particle with kinetic energy :math:`T` in the :math:`i`-th element can
+be calculated as:
+
+.. math::
+
+    E_{i} = \int_{0}^{R(T)} w_{i}S_{\text{col,i}} dx
+
+where :math:`R(T)` is the CSDA range of the charged particle,
+:math:`S_{\text{col},i}` is the collision stopping power of the charged particle
+in the :math:`i`-th element and :math:`w_i` is the mass fraction of the
+:math:`i`-th element. According to the Bethe formula the collision stopping
+power of the :math:`i`-th element is proportional to :math:`Z_i/A_i`, so the
+fractional collision stopping power from the :math:`i`-th element is:
+
+.. math::
+
+    \frac{w_{i}S_{\text{col},i}(T)}{S_{\text{col}}(T)} =
+    \frac{\frac{w_{i}Z_{i}}{A_{i}}}{\sum_{i}\frac{w_{i}Z_{i}}{A_{i}}} =
+    \frac{\gamma_i Z_{i}}{\sum_{i}\gamma_i Z_{i}}.
+
+where :math:`\gamma_i` is the atomic fraction of the :math:`i`-th element.
+Therefore, the energy deposited by charged particles should be attributed to
+a given element according to its fractional charge density.
+
 ----------
 References
 ----------

docs/source/pythonapi/base.rst

@@ -130,6 +130,7 @@ Constructing Tallies
    openmc.MeshFilter
    openmc.MeshBornFilter
    openmc.ImportanceFilter
+   openmc.MeshMaterialFilter
    openmc.MeshSurfaceFilter
    openmc.EnergyFilter
    openmc.EnergyoutFilter

docs/source/pythonapi/deplete.rst

@@ -206,14 +206,15 @@ total system energy.
 The :class:`openmc.deplete.IndependentOperator` uses inner classes subclassed
 from those listed above to perform similar calculations.
 
-The following classes are used to define transfer rates to model continuous
-removal or feed of nuclides during depletion.
+The following classes are used to define external source rates or transfer rates
+to model continuous removal or feed of nuclides during depletion.
 
 .. autosummary::
    :toctree: generated
    :nosignatures:
    :template: myclass.rst
 
+   transfer_rates.ExternalSourceRates
    transfer_rates.TransferRates
 
 Intermediate Classes

docs/source/usersguide/data.rst

@@ -30,7 +30,8 @@ responsible for specifying one or more of the following:
 Each of the above files can specified in several ways. In the Python API, a
 :ref:`runtime configuration variable <usersguide_data_runtime>`
 :data:`openmc.config` can be used to specify any of the above and is initialized
-using a set of environment variables.
+using a set of environment variables. Data configuration paths set in
+:data:`openmc.config` will be expanded to absolute paths.
 
 .. _usersguide_data_runtime:
 

docs/source/usersguide/install.rst

@@ -221,7 +221,7 @@ Prerequisites
       OpenMC's built-in plotting capabilities use the libpng library to produce
       compressed PNG files. In the absence of this library, OpenMC will fallback
       to writing PPM files, which are uncompressed and only supported by select
-      image viewers. libpng can be installed on Ddebian derivates with::
+      image viewers. libpng can be installed on Debian derivates with::
 
           sudo apt install libpng-dev
 

include/openmc/boundary_condition.h

@@ -111,6 +111,10 @@ class PeriodicBC : public BoundaryCondition {
 
   std::string type() const override { return "periodic"; }
 
+  int i_surf() const { return i_surf_; }
+
+  int j_surf() const { return j_surf_; }
+
 protected:
   int i_surf_;
   int j_surf_;

include/openmc/material.h

@@ -107,6 +107,10 @@ class Material {
   //! \return Density in [g/cm^3]
   double density_gpcc() const { return density_gpcc_; }
 
+  //! Get charge density in [e/b-cm]
+  //! \return Charge density in [e/b-cm]
+  double charge_density() const { return charge_density_; };
+
   //! Get name
   //! \return Material name
   const std::string& name() const { return name_; }
@@ -177,6 +181,7 @@ class Material {
   xt::xtensor<double, 1> atom_density_; //!< Nuclide atom density in [atom/b-cm]
   double density_;                      //!< Total atom density in [atom/b-cm]
   double density_gpcc_;                 //!< Total atom density in [g/cm^3]
+  double charge_density_;               //!< Total charge density in [e/b-cm]
   double volume_ {-1.0};                //!< Volume in [cm^3]
   vector<bool> p0_; //!< Indicate which nuclides are to be treated with
                     //!< iso-in-lab scattering

include/openmc/particle_data.h

@@ -584,7 +584,8 @@ class ParticleData : public GeometryState {
   bool& fission() { return fission_; }            // true if implicit fission
   int& event_nuclide() { return event_nuclide_; } // index of collision nuclide
   const int& event_nuclide() const { return event_nuclide_; }
-  int& event_mt() { return event_mt_; }           // MT number of collision
+  int& event_mt() { return event_mt_; } // MT number of collision
+  const int& event_mt() const { return event_mt_; }
   int& delayed_group() { return delayed_group_; } // delayed group
   const int& parent_nuclide() const { return parent_nuclide_; }
   int& parent_nuclide() { return parent_nuclide_; } // Parent nuclide

include/openmc/tallies/filter.h

@@ -34,6 +34,7 @@ enum class FilterType {
   MESH,
   MESHBORN,
   IMPORTANCE,
+  MESH_MATERIAL,
   MESH_SURFACE,
   MU,
   MUSURFACE,