Updated cross_sections.rst to include a description of the MG mode op…

…tions

docs/source/methods/cross_sections.rst

@@ -1,16 +1,20 @@
 .. _methods_cross_sections:
 
-============================
-Cross Section Representation
-============================
-
-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.
+=============================
+Cross Section Representations
+=============================
+
+----------------------
+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,6 @@ 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,11 +60,102 @@ 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_.
 
+----------------
+Multi-Group Data
+----------------
+
+The data governing the interaction of neutrons with various nuclei or materials
+are represented using a multi-group library format specific to the OpenMC code.
+The format is described in the MGXS library specification_
+The data itself can be prepared via multiple paths including: generation via
+NJOY_ and TRANSX_, or directly from a continuous-energy OpenMC calculation by
+use of the Python API as is shown in the Python API example_ notebooks. This
+multi-group library consists of library 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 fission spectrum
+data (:math:`\chi{g'}`) and a fission production cross section
+(:math:`\nu\sigma_{f,g}`), or, a fission production matrix cross section
+(:math:`\nu\sigma_{f,g\arrow\g'}`).  If fission or energy release from fission
+tallies are requested by the user, then 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}`).
+
+After a scattering collision, the outgoing neutron experiences a change in both
+energy and angle. The probability of a neutron resulting in a given outgoing
+energy group (`g'`) given a certain incoming energy group (`g`) is provided
+by the scattering matrix cross sections themselves.  The angular information,
+however, can be expressed either via Legendre expansion of the neutron's
+change-in-angle (:math:`\mu`), a tabular representation of the probability of
+a neutron experiencing a given :math:`\mu`, or a histogram representation of the
+probability of a neutron experiencing a given :math:`\mu`. The formats used to
+represent these are described in the library format specification_.
+
+Unlike the continuous-energy mode, the multi-group mode does not explicitly
+track neutrons produced from scattering multiplication (i.e., :math:`(n,xn)`)
+reactions.  These are instead accounted for by adjusting the weight of the
+neutron after the collision such that the correct total weight is maintained.
+The information for how to adjust this weight is optionally provided by the
+`multiplicity` data which exists as a group-wise matrix. This data represents
+the average number of neutrons emitted from a scattering reaction, given a
+scattering reaction has occurred:
+
+.. math::
+
+    multiplicity_{g \arrow g'} = \frac{\nu_{scatter}\sigma_{s,g \arrow g'}}{
+    								   \sigma_{s,g \arrow g'}}
+
+This data is provided as a group-wise matrix since the probability of producing
+multiple neutrons in a scattering reaction depends on both the incoming energy,
+`g`, and the sampled outgoing energy, `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 neutrons produced in scattering multiplication reactions.
+However, this assumption will result in a loss of accuracy since the total
+neutron population would not be conserved. This reduction in accuracy due to
+the loss in neutron conservation can be mitigated by reducing the absorption
+cross section as needed to maintain neutron 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 \arrow g'}}
+
+The above method is the same as is typically done with most deterministic methods.
+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 neutrons produced in
+these reactions.
+
+All of the data discussed in this section can be provided to the code
+independent of the neutron's direction of motion (i.e., isotropic), or the data
+can be provided as a tabular distribution of the polar and azimuthal neutron
+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
 
    .. rubric:: References
@@ -75,3 +168,6 @@ can be found in a paper by Leppanen_.
 .. _NJOY: http://t2.lanl.gov/codes.shtml
 .. _ENDF/B data: http://www.nndc.bnl.gov/endf
 .. _Leppanen: http://dx.doi.org/10.1016/j.anucene.2009.03.019
+.. _specification: ENTER LINK
+.. _TRANSX: ENTER LINK
+.. _example: ENTER LINK

docs/source/methods/introduction.rst

@@ -56,9 +56,9 @@ following steps:
     combined to produce material-specific cross section data.
 
   - In a fixed source problem, source sites are sampled from the specified
-    source. In an eigenvalue problem, source sites are sampled from some initial
-    source distribution or from a source file. The source sites consist of
-    coordinates, a direction, and an energy.
+    source. In an eigenvalue problem, source sites are sampled from some
+    initial source distribution or from a source file. The source sites
+    consist of coordinates, a direction, and an energy.
 
 Once initialization is complete, the actual transport simulation can
 proceed. The life of a single particle will proceed as follows: