Merge branch 'mg_docs' into develop

docs/source/methods/cross_sections.rst

@@ -1,16 +1,20 @@
 .. _methods_cross_sections:
 
-============================
-Cross Section Representation
-============================
+=============================
+Cross Section Representations
+=============================
 
-The data governing the interaction of neutrons with various nuclei are
-represented using the ACE format which is used by MCNP_ and Serpent_. ACE-format
-data can be generated with the NJOY_ nuclear data processing system which
-converts raw `ENDF/B data`_ into linearly-interpolable data as required by most
-Monte Carlo codes. The use of a standard cross section format allows for a
-direct comparison of OpenMC with other codes since the same cross section
-libraries can be used.
+----------------------
+Continuous-Energy Data
+----------------------
+
+The data governing the interaction of neutrons with
+various nuclei for continous-energy problems are represented using the ACE
+format which is used by MCNP_ and Serpent_. ACE-format data can be generated
+with the NJOY_ nuclear data processing system which converts raw
+`ENDF/B data`_ into linearly-interpolable data as required by most Monte Carlo
+codes. The use of a standard cross section format allows for a direct comparison
+of OpenMC with other codes since the same cross section libraries can be used.
 
 The ACE format contains continuous-energy cross sections for the following types
 of reactions: elastic scattering, fission (or first-chance fission,
@@ -24,7 +28,6 @@ accurate treatment of self-shielding in the unresolved resonance range. For
 bound scatterers, separate tables with :math:`S(\alpha,\beta,T)` scattering law
 data can be used.
 
--------------------
 Energy Grid Methods
 -------------------
 
@@ -48,7 +51,7 @@ implement a method of reducing the number of energy grid searches in order to
 speed up the calculation.
 
 Logarithmic Mapping
--------------------
++++++++++++++++++++
 
 To speed up energy grid searches, OpenMC uses logarithmic mapping technique
 [Brown]_ to limit the range of energies that must be searched for each
@@ -58,12 +61,11 @@ the nuclide energy grids. By default, OpenMC uses 8000 equal-lethargy segments
 as recommended by Brown.
 
 Other Methods
--------------
++++++++++++++
 
 A good survey of other energy grid techniques, including unionized energy grids,
 can be found in a paper by Leppanen_.
 
----------------------------------
 Windowed Multipole Representation
 ---------------------------------
 
@@ -137,7 +139,98 @@ scattering does not occur in the resolved resonance region.  This is usually,
 but not always the case.  Future library versions may eliminate this issue.
 
 The data format used by OpenMC to represent windowed multipole data is specified
-in :ref:`io_data_wmp`
+in :ref:`io_data_wmp`.
+
+----------------
+Multi-Group Data
+----------------
+
+The data governing the interaction of particles with various nuclei or materials
+are represented using a multi-group library format specific to the OpenMC code.
+The format is described in the :ref:`mgxs_lib_spec`.
+The data itself can be prepared via traditional paths or directly from a
+continuous-energy OpenMC calculation by use of the Python API as is shown in the
+:ref:`notebook_mgxs_part_iv` example notebook. This multi-group
+library consists of meta-data (such as the energy group structure) and multiple
+`xsdata` objects which contains the required microscopic or macroscopic
+multi-group data.
+
+At a minimum, the library must contain the absorption cross section
+(:math:`\sigma_{a,g}`) and a scattering matrix. If the problem is an eigenvalue
+problem then all fissionable materials must also contain either
+a fission production matrix cross section
+(:math:`\nu\sigma_{f,g\rightarrow g'}`), or
+both the fission spectrum data (:math:`\chi_{g'}`) and a fission production
+cross section (:math:`\nu\sigma_{f,g}`), or, .  The library must also contain
+the fission cross section (:math:`\sigma_{f,g}`) or the fission energy release
+cross section (:math:`\kappa\sigma_{f,g}`) if the associated tallies are
+required by the model using the library.
+
+After a scattering collision, the outgoing particle experiences a change in both
+energy and angle. The probability of a particle resulting in a given outgoing
+energy group (`g'`) given a certain incoming energy group (`g`) is provided
+by the scattering matrix data.  The angular information can be expressed either
+via Legendre expansion of the particle's change-in-angle (:math:`\mu`), a
+tabular representation of the probability distribution function of :math:`\mu`,
+or a histogram representation of the same PDF. The formats used to
+represent these are described in the :ref:`mgxs_lib_spec`.
+
+Unlike the continuous-energy mode, the multi-group mode does not explicitly
+track particles produced from scattering multiplication (i.e., :math:`(n,xn)`)
+reactions.  These are instead accounted for by adjusting the weight of the
+particle after the collision such that the correct total weight is maintained.
+The weight adjustment factor is optionally provided by the `multiplicity` data
+which is required to be provided in the form of a group-wise matrix.
+This data is provided as a group-wise matrix since the probability of producing
+multiple particles in a scattering reaction depends on both the incoming energy,
+`g`, and the sampled outgoing energy, `g'`. This data represents the average
+number of particles emitted from a scattering reaction, given a scattering
+reaction has occurred:
+
+.. math::
+
+    multiplicity_{g \rightarrow g'} = \frac{\nu_{scatter}\sigma_{s,g \rightarrow g'}}{
+    								   \sigma_{s,g \rightarrow g'}}
+
+If this scattering multiplication information is not provided in the library
+then no weight adjustment will be performed. This is equivalent to neglecting
+any additional particles produced in scattering multiplication reactions.
+However, this assumption will result in a loss of accuracy since the total
+particle population would not be conserved. This reduction in accuracy due to
+the loss in particle conservation can be mitigated by reducing the absorption
+cross section as needed to maintain particle conservation. This adjustment can
+be done when generating the library, or by OpenMC. To have OpenMC perform the
+adjustment, the total cross section (:math:`\sigma_{t,g}`) must be provided.
+With this information, OpenMC will then adjust the absorption cross section as
+follows:
+
+.. math::
+
+    \sigma_{a,g} = \sigma_{t,g} - \sum_{g'}\nu_{scatter}\sigma_{s,g \rightarrow g'}
+
+The above method is the same as is usually done with most deterministic solvers.
+Note that this method is less accurate than using the scattering multiplication
+weight adjustment since simply reducing the absorption cross section does not
+include any information about the outgoing energy of the particles produced in
+these reactions.
+
+All of the data discussed in this section can be provided to the code
+independent of the particle's direction of motion (i.e., isotropic), or the data
+can be provided as a tabular distribution of the polar and azimuthal particle
+direction angles. The isotropic representation is the most commonly used,
+however inaccuracies are to be expected especially near material interfaces
+where a material has a very large cross sections relative to the other material
+(as can be expected in the resonance range). The angular representation can be
+used to minimize this error.
+
+Finally, the above options for representing the physics do not have to be
+consistent across the problem.  The number of groups and the structure, however,
+does have to be consistent across the data sets. That is to say that each
+microscopic or macroscopic data set does not have to apply the same scattering
+expansion, treatment of multiplicity or angular representation of the cross
+sections. This allows flexibility for the model to use highly anisotropic
+scattering information in the water while the fuel can be simulated with linear
+or even isotropic scattering.
 
 .. only:: html