From 6fac1367ec15fc6ee45fcfd220be2205de2b5f88 Mon Sep 17 00:00:00 2001 From: Paul Romano Date: Tue, 20 Feb 2018 14:43:26 -0600 Subject: [PATCH] Improve depletion reference documentation --- docs/source/conf.py | 1 + docs/source/pythonapi/deplete.rst | 98 +++++++++++++++++-------------- openmc/deplete/abc.py | 2 + openmc/deplete/atom_number.py | 2 - openmc/deplete/chain.py | 7 +++ openmc/deplete/integrator/cecm.py | 2 +- openmc/deplete/nuclide.py | 50 +++++++++++++--- openmc/deplete/operator.py | 7 ++- openmc/deplete/reaction_rates.py | 3 - openmc/deplete/results.py | 86 +++++++++++++-------------- 10 files changed, 155 insertions(+), 103 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index b25d5abbe..a2fec39b7 100644 --- a/docs/source/conf.py +++ b/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 diff --git a/docs/source/pythonapi/deplete.rst b/docs/source/pythonapi/deplete.rst index 13f2fd155..1d1a1c0ee 100644 --- a/docs/source/pythonapi/deplete.rst +++ b/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 diff --git a/openmc/deplete/abc.py b/openmc/deplete/abc.py index f2fa73650..8b42ee800 100644 --- a/openmc/deplete/abc.py +++ b/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): diff --git a/openmc/deplete/atom_number.py b/openmc/deplete/atom_number.py index 8f6a41911..9a32dfa3a 100644 --- a/openmc/deplete/atom_number.py +++ b/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] diff --git a/openmc/deplete/chain.py b/openmc/deplete/chain.py index 0cd3fb0d7..23395329e 100644 --- a/openmc/deplete/chain.py +++ b/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 diff --git a/openmc/deplete/integrator/cecm.py b/openmc/deplete/integrator/cecm.py index db58d5d52..9a07cd198 100644 --- a/openmc/deplete/integrator/cecm.py +++ b/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 `_. This algorithm is mathematically defined as: diff --git a/openmc/deplete/nuclide.py b/openmc/deplete/nuclide.py index 4a7b86f02..af10e5c2f 100644 --- a/openmc/deplete/nuclide.py +++ b/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 """ diff --git a/openmc/deplete/operator.py b/openmc/deplete/operator.py index d0a64a06d..1c62bdd40 100644 --- a/openmc/deplete/operator.py +++ b/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 ---------- diff --git a/openmc/deplete/reaction_rates.py b/openmc/deplete/reaction_rates.py index 482c357a2..fddb88b19 100644 --- a/openmc/deplete/reaction_rates.py +++ b/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): diff --git a/openmc/deplete/results.py b/openmc/deplete/results.py index 307d18a40..f27353a4e 100644 --- a/openmc/deplete/results.py +++ b/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.