Improve fission energy release documentation

docs/source/io_formats/fission_energy.rst

@@ -0,0 +1,53 @@
+.. _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 Z and their A numbers.  For
+    example, U235 is named 92235.  Metastable nuclides are appended with an
+    '_m' and their metastable number.  For example, the first excited isomer
+    of Am-242 is named 95242_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

@@ -335,6 +335,7 @@ Core Classes
     openmc.data.Tabulated1D
     openmc.data.ThermalScattering
     openmc.data.CoherentElastic
+    openmc.data.FissionEnergyRelease
 
 Angle-Energy Distributions
 --------------------------
@@ -368,21 +369,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/