Improve depletion reference documentation

docs/source/conf.py

@@ -32,6 +32,7 @@ MOCK_MODULES = [
 sys.modules.update((mod_name, MagicMock()) for mod_name in MOCK_MODULES)
 
 import numpy as np
+np.ndarray = MagicMock
 np.polynomial.Polynomial = MagicMock
 
 

docs/source/pythonapi/deplete.rst

@@ -4,59 +4,71 @@
 :mod:`openmc.deplete` -- Depletion
 ----------------------------------
 
-Integrators
------------
+.. module:: openmc.deplete
+
+Two functions are provided that implement different time-integration algorithms
+for depletion calculations.
 
 .. autosummary::
    :toctree: generated
    :nosignatures:
    :template: myfunction.rst
 
-   openmc.deplete.integrator.predictor
-   openmc.deplete.integrator.cecm
+   integrator.predictor
+   integrator.cecm
 
-Integrator Helper Functions
----------------------------
+Each of these functions expects a "transport operator" to be passed. An operator
+specific to OpenMC is available using the following class:
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myclass.rst
+
+   Operator
+
+Internal Classes and Functions
+------------------------------
+
+During a depletion calculation, the depletion chain, reaction rates, and number
+densities are managed through a series of internal classes that are not normally
+visible to a user. However, should you find yourself wondering about these
+classes (e.g., if you want to know what decay modes or reactions are present in
+a depletion chain), they are documented here. The following classes store data
+for a depletion chain:
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myclass.rst
+
+   Chain
+   DecayTuple
+   Nuclide
+   ReactionTuple
+
+The following classes are used during a depletion simulation and store auxiliary
+data, such as number densities and reaction rates for each material.
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myclass.rst
+
+   AtomNumber
+   OperatorResult
+   ReactionRates
+   Results
+   TransportOperator
+
+Each of the integrator functions also relies on a number of "helper" functions
+as follows:
 
 .. autosummary::
    :toctree: generated
    :nosignatures:
    :template: myfunction.rst
 
-   openmc.deplete.integrator.CRAM16
-   openmc.deplete.integrator.CRAM48
-   openmc.deplete.integrator.save_results
-
-Metaclasses
------------
-
-.. autosummary::
-   :toctree: generated
-   :nosignatures:
-   :template: myclass.rst
-
-   openmc.deplete.TransportOperator
-
-OpenMC Classes
---------------
-
-.. autosummary::
-   :toctree: generated
-   :nosignatures:
-   :template: myclass.rst
-
-   openmc.deplete.Operator
-   openmc.deplete.OperatorResult
-
-Data Classes
-------------
-.. autosummary::
-   :toctree: generated
-   :nosignatures:
-   :template: myclass.rst
-
-   openmc.deplete.AtomNumber
-   openmc.deplete.Chain
-   openmc.deplete.Nuclide
-   openmc.deplete.ReactionRates
-   openmc.deplete.Results
+   integrator.CRAM16
+   integrator.CRAM48
+   integrator.save_results

openmc/deplete/abc.py

@@ -23,6 +23,8 @@ rates : openmc.deplete.ReactionRates
     Resulting reaction rates
 
 """
+OperatorResult.k.__doc__ = None
+OperatorResult.rates.__doc__ = None
 
 
 class TransportOperator(metaclass=ABCMeta):

openmc/deplete/atom_number.py

@@ -113,12 +113,10 @@ class AtomNumber(object):
 
     @property
     def n_nuc(self):
-        """Number of nuclides."""
         return len(self.index_nuc)
 
     @property
     def burnable_nuclides(self):
-        """All burnable nuclide names. Used for sorting the simulation."""
         return [nuc for nuc, ind in self.index_nuc.items()
                 if ind < self.n_nuc_burn]
 

openmc/deplete/chain.py

@@ -111,6 +111,13 @@ def replace_missing(product, decay_data):
 class Chain(object):
     """Full representation of a depletion chain.
 
+    A depletion chain can be created by using the :meth:`from_endf` method which
+    requires a list of ENDF incident neutron, decay, and neutron fission product
+    yield sublibrary files. The depletion chain used during a depletion
+    simulation is indicated by either an argument to
+    :class:`openmc.deplete.Operator` or through the
+    :envvar:`OPENMC_DEPLETE_CHAIN` environment variable.
+
     Attributes
     ----------
     nuclides : list of openmc.deplete.Nuclide

openmc/deplete/integrator/cecm.py

@@ -10,7 +10,7 @@ from .save_results import save_results
 def cecm(operator, timesteps, power, print_out=True):
     r"""Deplete using the CE/CM algorithm.
 
-    Implements the second order `CE/CM Predictor-Corrector algorithm
+    Implements the second order `CE/CM predictor-corrector algorithm
     <https://doi.org/10.13182/NSE14-92>`_.  This algorithm is mathematically
     defined as:
 

openmc/deplete/nuclide.py

@@ -9,14 +9,50 @@ try:
 except ImportError:
     import xml.etree.ElementTree as ET
 
+
 DecayTuple = namedtuple('DecayTuple', 'type target branching_ratio')
+DecayTuple.__doc__ = """\
+Decay mode information
+
+Parameters
+----------
+type : str
+    Type of the decay mode, e.g., 'beta-'
+target : str
+    Nuclide resulting from decay
+branching_ratio : float
+    Branching ratio of the decay mode
+
+"""
+DecayTuple.type.__doc__ = None
+DecayTuple.target.__doc__ = None
+DecayTuple.branching_ratio.__doc__ = None
+
+
 ReactionTuple = namedtuple('ReactionTuple', 'type target Q branching_ratio')
+ReactionTuple.__doc__ = """\
+Transmutation reaction information
+
+Parameters
+----------
+type : str
+    Type of the reaction, e.g., 'fission'
+target : str
+    nuclide resulting from reaction
+Q : float
+    Q value of the reaction in [eV]
+branching_ratio : float
+    Branching ratio of the reaction
+
+"""
+ReactionTuple.type.__doc__ = None
+ReactionTuple.target.__doc__ = None
+ReactionTuple.Q.__doc__ = None
+ReactionTuple.branching_ratio.__doc__ = None
 
 
 class Nuclide(object):
-    """The Nuclide class.
-
-    Contains everything in a depletion chain relating to a single nuclide.
+    """Decay modes, reactions, and fission yields for a single nuclide.
 
     Attributes
     ----------
@@ -28,12 +64,12 @@ class Nuclide(object):
         Energy deposited from decay in [eV].
     n_decay_modes : int
         Number of decay pathways.
-    decay_modes : list of DecayTuple
+    decay_modes : list of openmc.deplete.DecayTuple
         Decay mode information. Each element of the list is a named tuple with
         attributes 'type', 'target', and 'branching_ratio'.
     n_reaction_paths : int
         Number of possible reaction pathways.
-    reactions : list of ReactionTuple
+    reactions : list of openmc.deplete.ReactionTuple
         Reaction information. Each element of the list is a named tuple with
         attribute 'type', 'target', 'Q', and 'branching_ratio'.
     yield_data : dict of float to list
@@ -62,12 +98,10 @@ class Nuclide(object):
 
     @property
     def n_decay_modes(self):
-        """Number of decay modes."""
         return len(self.decay_modes)
 
     @property
     def n_reaction_paths(self):
-        """Number of possible reaction pathways."""
         return len(self.reactions)
 
     @classmethod
@@ -81,7 +115,7 @@ class Nuclide(object):
 
         Returns
         -------
-        nuc : Nuclide
+        nuc : openmc.deplete.Nuclide
             Instance of a nuclide
 
         """

openmc/deplete/operator.py

@@ -50,7 +50,12 @@ def _distribute(items):
 
 
 class Operator(TransportOperator):
-    """OpenMC transport operator for depletion
+    """OpenMC transport operator for depletion.
+
+    Instances of this class can be used to perform depletion using OpenMC as the
+    transport operator. Normally, a user needn't call methods of this class
+    directly. Instead, an instance of this class is passed to an integrator
+    function, such as :func:`openmc.deplete.integrator.cecm`.
 
     Parameters
     ----------

openmc/deplete/reaction_rates.py

@@ -85,17 +85,14 @@ class ReactionRates(np.ndarray):
 
     @property
     def n_mat(self):
-        """Number of materials."""
         return len(self.index_mat)
 
     @property
     def n_nuc(self):
-        """Number of nucs."""
         return len(self.index_nuc)
 
     @property
     def n_react(self):
-        """Number of reactions."""
         return len(self.index_rx)
 
     def get(self, mat, nuc, rx):

openmc/deplete/results.py

@@ -58,51 +58,6 @@ class Results(object):
 
         self.data = None
 
-    def allocate(self, volume, nuc_list, burn_list, full_burn_list, stages):
-        """Allocates memory of Results.
-
-        Parameters
-        ----------
-        volume : dict of str float
-            Volumes corresponding to materials in full_burn_dict
-        nuc_list : list of str
-            A list of all nuclide names. Used for sorting the simulation.
-        burn_list : list of int
-            A list of all mat IDs to be burned.  Used for sorting the simulation.
-        full_burn_list : list of str
-            List of all burnable material IDs
-        stages : int
-            Number of stages in simulation.
-
-        """
-        self.volume = copy.deepcopy(volume)
-        self.nuc_to_ind = {nuc: i for i, nuc in enumerate(nuc_list)}
-        self.mat_to_ind = {mat: i for i, mat in enumerate(burn_list)}
-        self.mat_to_hdf5_ind = {mat: i for i, mat in enumerate(full_burn_list)}
-
-        # Create storage array
-        self.data = np.zeros((stages, self.n_mat, self.n_nuc))
-
-    @property
-    def n_mat(self):
-        """Number of mats."""
-        return len(self.mat_to_ind)
-
-    @property
-    def n_nuc(self):
-        """Number of nuclides."""
-        return len(self.nuc_to_ind)
-
-    @property
-    def n_hdf5_mats(self):
-        """Number of materials in entire geometry."""
-        return len(self.mat_to_hdf5_ind)
-
-    @property
-    def n_stages(self):
-        """Number of stages in simulation."""
-        return self.data.shape[0]
-
     def __getitem__(self, pos):
         """Retrieves an item from results.
 
@@ -149,6 +104,47 @@ class Results(object):
 
         self.data[stage, mat, nuc] = val
 
+    @property
+    def n_mat(self):
+        return len(self.mat_to_ind)
+
+    @property
+    def n_nuc(self):
+        return len(self.nuc_to_ind)
+
+    @property
+    def n_hdf5_mats(self):
+        return len(self.mat_to_hdf5_ind)
+
+    @property
+    def n_stages(self):
+        return self.data.shape[0]
+
+    def allocate(self, volume, nuc_list, burn_list, full_burn_list, stages):
+        """Allocates memory of Results.
+
+        Parameters
+        ----------
+        volume : dict of str float
+            Volumes corresponding to materials in full_burn_dict
+        nuc_list : list of str
+            A list of all nuclide names. Used for sorting the simulation.
+        burn_list : list of int
+            A list of all mat IDs to be burned.  Used for sorting the simulation.
+        full_burn_list : list of str
+            List of all burnable material IDs
+        stages : int
+            Number of stages in simulation.
+
+        """
+        self.volume = copy.deepcopy(volume)
+        self.nuc_to_ind = {nuc: i for i, nuc in enumerate(nuc_list)}
+        self.mat_to_ind = {mat: i for i, mat in enumerate(burn_list)}
+        self.mat_to_hdf5_ind = {mat: i for i, mat in enumerate(full_burn_list)}
+
+        # Create storage array
+        self.data = np.zeros((stages, self.n_mat, self.n_nuc))
+
     def create_hdf5(self, handle):
         """Creates file structure for a blank HDF5 file.