Merge branch 'fission_q' into poly_and_fission_q

docs/source/io_formats/fission_energy.rst

@@ -0,0 +1,52 @@
+.. _usersguide_fission_energy:
+
+==================================
+Fission Energy Release File Format
+==================================
+
+This file is a compact HDF5 representation of the ENDF MT=1, MF=458 data (see
+ENDF-102_ for details).  It gives the information needed to compute the energy
+carried away from fission reactions by each reaction product (e.g. fragment
+nuclei, neutrons) which depends on the incident neutron energy.  OpenMC is
+distributed with one of these files under
+openmc/data/fission_Q_data_endfb71.h5.  More files of this format can be
+created from ENDF files with the
+``openmc.data.write_compact_458_library`` function.  They can be read with the
+``openmc.data.FissionEnergyRelease.from_compact_hdf5`` class method.
+
+:Attributes: - **comment** (*char[]*) -- An optional text comment
+             - **component order** (*char[][]*) -- An array of strings
+               specifying the order each reaction product occurs in the data
+               arrays.  The components use the 2-3 letter abbreviations
+               specified in ENDF-102 e.g. EFR for fission fragments and ENP for
+               prompt neutrons.
+
+**/<nuclide name>/**
+    Nuclides are named by concatenating their atomic symbol and mass number. For
+    example, 'U235' or 'Pu239'.  Metastable nuclides are appended with an
+    '_m' and their metastable number.  For example, 'Am242_m1'
+
+:Datasets: - **data** (*double[][][]*) -- The energy release coefficients.  The
+             first axis indexes the component type.  The second axis specifies
+             values or uncertainties.  The third axis indexes the polynomial
+             order.  If the data uses the Sher-Beck format, then the last axis
+             will have a length of one and ENDF-102 should be consulted for
+             energy dependence.  Otherwise, the data uses the Madland format
+             which is a polynomial of incident energy.
+
+             For example, if 'EFR' is given first in the **component order**
+             attribute and the data uses the Madland format, then the energy
+             released in the form of fission fragments at an incident energy
+             :math:`E` is given by
+
+             .. math::
+                \text{data}[0, 0, 0] + \text{data}[0, 0, 1] \cdot E
+                + \text{data}[0, 0, 2] \cdot E^2 + \ldots
+              
+             And its uncertainty is
+
+             .. math::
+                \text{data}[0, 1, 0] + \text{data}[0, 1, 1] \cdot E
+                + \text{data}[0, 1, 2] \cdot E^2 + \ldots
+
+.. _ENDF-102: http://www.nndc.bnl.gov/endfdocs/ENDF-102-2012.pdf

docs/source/io_formats/index.rst

@@ -15,6 +15,7 @@ Data Files
    nuclear_data
    mgxs_library
    data_wmp
+   fission_energy
 
 ------------
 Output Files

docs/source/io_formats/nuclear_data.rst

@@ -55,6 +55,27 @@ Incident Neutron Data
    from fission. It is formatted as a reaction product, described in
    :ref:`product`.
 
+**/<nuclide name>/fission_energy_release/**
+
+:Attributes: - **format** (*char[]*) -- The energy-dependence format.  Either
+               'Madland' or 'Sher-Beck'
+
+:Datasets: - **fragments** (*double[]*) -- Polynomial coefficients for energy
+             released in the form of fragments
+           - **prompt_neutrons** (*double[]* or :ref:`tabulated <1d_tabulated>`)
+             -- Energy released in the form of prompt neutrons.  Polynomial if
+             the format is Madland or a table if Sher-Beck.
+           - **delayed_neutrons** (*double[]*) -- Polynomial coefficients for
+             energy released in the form of delayed neutrons
+           - **prompt_photons** (*double[]*) -- Polynomial coefficients for
+             energy released in the form of prompt photons
+           - **delayed_photons** (*double[]*) -- Polynomial coefficients for
+             energy released in the form of delayed photons
+           - **betas** (*double[]*) -- Polynomial coefficients for
+             energy released in the form of betas
+           - **neutrinos** (*double[]*) -- Polynomial coefficients for
+             energy released in the form of neutrinos
+
 -------------------------------
 Thermal Neutron Scattering Data
 -------------------------------

docs/source/pythonapi/index.rst

@@ -348,6 +348,7 @@ Core Classes
     openmc.data.Tabulated1D
     openmc.data.ThermalScattering
     openmc.data.CoherentElastic
+    openmc.data.FissionEnergyRelease
 
 Angle-Energy Distributions
 --------------------------
@@ -381,21 +382,22 @@ Classes
 +++++++
 
 .. autosummary::
-   :toctree: generated
-   :nosignatures:
-   :template: myclass.rst
+    :toctree: generated
+    :nosignatures:
+    :template: myclass.rst
 
-   openmc.data.ace.Library
-   openmc.data.ace.Table
+    openmc.data.ace.Library
+    openmc.data.ace.Table
 
 Functions
 +++++++++
 
 .. autosummary::
-   :toctree: generated
-   :nosignatures:
+    :toctree: generated
+    :nosignatures:
 
-   openmc.data.ace.ascii_to_binary
+    openmc.data.ace.ascii_to_binary
+    openmc.data.write_compact_458_library
 
 .. _Jupyter: https://jupyter.org/
 .. _NumPy: http://www.numpy.org/

docs/source/usersguide/input.rst

@@ -1809,6 +1809,27 @@ The ``<tally>`` element accepts the following sub-elements:
         |                      |:math:`\gamma`-rays are assumed to deposit their   |
         |                      |energy locally. Units are MeV per source particle. |
         +----------------------+---------------------------------------------------+
+        |fission-q-prompt      |The prompt fission energy production rate. This    |
+        |                      |energy comes in the form of fission fragment       |
+        |                      |nuclei, prompt neutrons, and prompt                |
+        |                      |:math:`\gamma`-rays. This value depends on the     |
+        |                      |incident energy and it requires that the nuclear   |
+        |                      |data library contains the optional fission energy  |
+        |                      |release data. Energy is assumed to be deposited    |
+        |                      |locally. Units are MeV per source particle.        |
+        +----------------------+---------------------------------------------------+
+        |fission-q-recoverable |The recoverable fission energy production rate.    |
+        |                      |This energy comes in the form of fission fragment  |
+        |                      |nuclei, prompt and delayed neutrons, prompt and    |
+        |                      |delayed :math:`\gamma`-rays, and delayed           |
+        |                      |:math:`\beta`-rays. This tally differs from the    |
+        |                      |kappa-fission tally in that it is dependent on     |
+        |                      |incident neutron energy and it requires that the   |
+        |                      |nuclear data library contains the optional fission |
+        |                      |energy release data. Energy is assumed to be       |
+        |                      |deposited locally. Units are MeV per source        |
+        |                      |paticle.                                           |
+        +----------------------+---------------------------------------------------+
 
     .. note::
        The ``analog`` estimator is actually identical to the ``collision``