From 2428702fb653617658b99319a232f9b76454ee91 Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Tue, 17 Sep 2019 11:11:39 -0500 Subject: [PATCH 1/4] Improved documentation for depletion module * __call__ methods for Operator documented * CRAM16 and CRAM48 are closer to the top of the page * Document deplete and timed_deplete functions * Abstract integrators documented as part of abc submodule * Abstract operator helpers documented as part of abc submodule --- docs/source/_templates/mycallable.rst | 9 ++++++++ docs/source/pythonapi/deplete.rst | 30 ++++++++++++++------------- 2 files changed, 25 insertions(+), 14 deletions(-) create mode 100644 docs/source/_templates/mycallable.rst diff --git a/docs/source/_templates/mycallable.rst b/docs/source/_templates/mycallable.rst new file mode 100644 index 000000000..85fdd34c3 --- /dev/null +++ b/docs/source/_templates/mycallable.rst @@ -0,0 +1,9 @@ +{{ fullname }} +{{ underline }} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :members: + :special-members: __call__ + diff --git a/docs/source/pythonapi/deplete.rst b/docs/source/pythonapi/deplete.rst index 5b26eb38a..531723b72 100644 --- a/docs/source/pythonapi/deplete.rst +++ b/docs/source/pythonapi/deplete.rst @@ -31,7 +31,7 @@ specific to OpenMC is available using the following class: .. autosummary:: :toctree: generated :nosignatures: - :template: myclass.rst + :template: mycallable.rst Operator @@ -82,6 +82,19 @@ data, such as number densities and reaction rates for each material. Results ResultsList +The following functions are used to solve the depletion equations, with +:func:`cram.CRAM48` being the default. + +.. autosummary:: + :toctree: generated + :nosignatures: + :template: myfunction.rst + + cram.CRAM16 + cram.CRAM48 + cram.deplete + cram.timed_deplete + The following classes are used to help the :class:`openmc.deplete.Operator` compute quantities like effective fission yields, reaction rates, and total system energy. @@ -119,16 +132,5 @@ base classes: :nosignatures: :template: myintegrator.rst - Integrator - SIIntegrator - -Each of the integrator classes also relies on a number of "helper" functions -as follows: - -.. autosummary:: - :toctree: generated - :nosignatures: - :template: myfunction.rst - - cram.CRAM16 - cram.CRAM48 + abc.Integrator + abc.SIIntegrator From 72471d249fd4f0edda5ca4e26ad1fb1210a84247 Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Tue, 17 Sep 2019 14:56:31 -0500 Subject: [PATCH 2/4] Expand openmc.deplete documentation: minimal example and ABCs Slight reformatting of the depletion documentation. The "Primary API" is presented at the top, including integrators and the Operator. This section is followed by a "Minimal Example" that demonstrates how one might instantiate an Operator, and use it for depletion. The comm communicator is moved into the "Internal Classes and Functions" section, as the end-user is less likely to interact with this directly. Lastly, a section on "Abstract Base Classes" is provided and expanded, documenting the purpose of specific ABCs. --- docs/source/pythonapi/deplete.rst | 82 ++++++++++++++++++++++++++----- 1 file changed, 71 insertions(+), 11 deletions(-) diff --git a/docs/source/pythonapi/deplete.rst b/docs/source/pythonapi/deplete.rst index 531723b72..55725f3bc 100644 --- a/docs/source/pythonapi/deplete.rst +++ b/docs/source/pythonapi/deplete.rst @@ -6,7 +6,22 @@ .. module:: openmc.deplete -Several classes are provided that implement different time-integration +Primary API +----------- + +The two primary requirements to perform depletion with :mod:`openmc.deplete` +are: + + 1) A transport operator + 2) A time-integration scheme + +The former is responsible for executing a transport code, like OpenMC, +and retaining important information required for depletion. The most common examples +are reaction rates and power normalization data. The latter is responsible for +projecting reaction rates and compositions forward in calendar time across +some step size :math:`\Delta t`, and obtaining new compositions given a power +or power density. The :class:`Operator` is provided to handle communicating with +OpenMC. Several classes are provided that implement different time-integration algorithms for depletion calculations, which are described in detail in Colin Josey's thesis, `Development and analysis of high order neutron transport-depletion coupling algorithms `_. @@ -35,6 +50,38 @@ specific to OpenMC is available using the following class: Operator +The :class:`Operator` must also have some knowledge of how nuclides transmute +and decay. This is handled by the :class:`Chain` + +Minimal Example +--------------- + +A minimal example for performing depletion would be: + +.. code:: Python + + >>> import openmc + >>> import openmc.deplete + >>> geometry = openmc.Geometry.from_xml() + >>> settings = openmc.Settings.from_xml() + + # Representation of a depletion chain + >>> chain_file = "chain_casl.xml" + >>> operator = openmc.deplete.Operator( + ... geometry, settings, chain_file) + + # Set up 5 time steps of one day each + >>> dt = [24 * 60 * 60] * 5 + >>> power = 1E6 # constant power of 1 MW + + # Deplete using mid-point predictor-corrector + >>> cecm = openmc.deplete.CECMIntegrator( + ... operator, dt, power) + >>> cecm.integrate() + +Internal Classes and Functions +------------------------------ + When running in parallel using `mpi4py `_, the MPI intercommunicator used can be changed by modifying the following module variable. If it is not explicitly modified, it defaults to @@ -46,9 +93,6 @@ variable. If it is not explicitly modified, it defaults to :type: mpi4py.MPI.Comm -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 @@ -110,19 +154,35 @@ total system energy. helpers.DirectReactionRateHelper helpers.FissionYieldCutoffHelper -The following classes are abstract classes that can be used to extend the -:mod:`openmc.deplete` capabilities: + +Abstract Base Classes +--------------------- + +A good starting point for extending capabilities in :mod:`openmc.deplete` is +to examine the following abstract base classes. Custom classes can +inherit from :class:`abc.TransportOperator` to implement alternative +schemes for collecting reaction rates and other data from a transport code +prior to depleting materials + +.. autosummary:: + :toctree: generated + :nosignatures: + :template: mycallable.rst + + abc.TransportOperator + +The following classes are abstract classes used to pass information from +OpenMC simulations back on to the :class:`abc.TransportOperator` .. autosummary:: :toctree: generated :nosignatures: :template: myclass.rst - EnergyHelper - FissionYieldHelper - ReactionRateHelper - TalliedFissionYieldHelper - TransportOperator + abc.EnergyHelper + abc.FissionYieldHelper + abc.ReactionRateHelper + abc.TalliedFissionYieldHelper Custom integrators can be developed by subclassing from the following abstract base classes: From b3c5d98454baeb33462c0637f8944634d756303a Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Tue, 17 Sep 2019 15:13:19 -0500 Subject: [PATCH 3/4] Cleaner openmc.deplete namespace with __all__ Provide explicit __all__ lists for files in openmc/deplete containing classes that should be brought into the "primary" API. This prevents cluttering the openmc.deplete namespace caused by the wildcard imports ``` from .nuclide import * ... ``` The abc, cram, and helpers modules are imported simply as ``` from . import abc from . import cram from . import helpers ``` --- openmc/deplete/__init__.py | 5 ++++- openmc/deplete/abc.py | 7 +++++++ openmc/deplete/chain.py | 2 ++ openmc/deplete/cram.py | 2 -- openmc/deplete/nuclide.py | 4 ++++ openmc/deplete/operator.py | 3 +++ openmc/deplete/reaction_rates.py | 3 +++ openmc/deplete/results.py | 3 +++ openmc/deplete/results_list.py | 3 +++ 9 files changed, 29 insertions(+), 3 deletions(-) diff --git a/openmc/deplete/__init__.py b/openmc/deplete/__init__.py index 8c19615ec..f0b04c3de 100644 --- a/openmc/deplete/__init__.py +++ b/openmc/deplete/__init__.py @@ -35,7 +35,10 @@ from .nuclide import * from .chain import * from .operator import * from .reaction_rates import * -from .abc import * +from .atom_number import * from .results import * from .results_list import * from .integrators import * +from . import abc +from . import cram +from . import helpers diff --git a/openmc/deplete/abc.py b/openmc/deplete/abc.py index e0ed64645..565b9e2dc 100644 --- a/openmc/deplete/abc.py +++ b/openmc/deplete/abc.py @@ -24,6 +24,13 @@ from .results import Results from .chain import Chain from .results_list import ResultsList + +__all__ = [ + "OperatorResult", "TransportOperator", "ReactionRateHelper", + "EnergyHelper", "FissionYieldHelper", "TalliedFissionYieldHelper", + "Integrator", "SIIntegrator"] + + OperatorResult = namedtuple('OperatorResult', ['k', 'rates']) OperatorResult.__doc__ = """\ Result of applying transport operator diff --git a/openmc/deplete/chain.py b/openmc/deplete/chain.py index 510112c7c..a2f7db818 100644 --- a/openmc/deplete/chain.py +++ b/openmc/deplete/chain.py @@ -45,6 +45,8 @@ _REACTIONS = [ ] +__all__ = ["Chain"] + def replace_missing(product, decay_data): """Replace missing product with suitable decay daughter. diff --git a/openmc/deplete/cram.py b/openmc/deplete/cram.py index 67a455cb3..31049bb72 100644 --- a/openmc/deplete/cram.py +++ b/openmc/deplete/cram.py @@ -13,8 +13,6 @@ import scipy.sparse.linalg as sla from . import comm -__all__ = ["deplete", "timed_deplete", "CRAM16", "CRAM48"] - def deplete(chain, x, rates, dt, matrix_func=None): """Deplete materials using given reaction rates for a specified time diff --git a/openmc/deplete/nuclide.py b/openmc/deplete/nuclide.py index 8896180a8..ec1668dac 100644 --- a/openmc/deplete/nuclide.py +++ b/openmc/deplete/nuclide.py @@ -17,6 +17,10 @@ from numpy import empty from openmc.checkvalue import check_type +__all__ = [ + "DecayTuple", "ReactionTuple", "Nuclide", "FissionYield", + "FissionYieldDistribution"] + DecayTuple = namedtuple('DecayTuple', 'type target branching_ratio') DecayTuple.__doc__ = """\ diff --git a/openmc/deplete/operator.py b/openmc/deplete/operator.py index 86dbeb755..9800bb280 100644 --- a/openmc/deplete/operator.py +++ b/openmc/deplete/operator.py @@ -30,6 +30,9 @@ from .helpers import ( FissionYieldCutoffHelper, AveragedFissionYieldHelper) +__all__ = ["Operator", "OperatorResult"] + + def _distribute(items): """Distribute items across MPI communicator diff --git a/openmc/deplete/reaction_rates.py b/openmc/deplete/reaction_rates.py index cea2f1997..85c8d8998 100644 --- a/openmc/deplete/reaction_rates.py +++ b/openmc/deplete/reaction_rates.py @@ -7,6 +7,9 @@ from collections import OrderedDict import numpy as np +__all__ = ["ReactionRates"] + + class ReactionRates(np.ndarray): """Reaction rates resulting from a transport operator call diff --git a/openmc/deplete/results.py b/openmc/deplete/results.py index 6593d5fc5..b44739bc5 100644 --- a/openmc/deplete/results.py +++ b/openmc/deplete/results.py @@ -16,6 +16,9 @@ from .reaction_rates import ReactionRates _VERSION_RESULTS = (1, 0) +__all__ = ["Results"] + + class Results(object): """Output of a depletion run diff --git a/openmc/deplete/results_list.py b/openmc/deplete/results_list.py index 3b5166ed8..26bc8785f 100644 --- a/openmc/deplete/results_list.py +++ b/openmc/deplete/results_list.py @@ -5,6 +5,9 @@ from .results import Results, _VERSION_RESULTS from openmc.checkvalue import check_filetype_version +__all__ = ["ResultsList"] + + class ResultsList(list): """A list of openmc.deplete.Results objects From 7a2b52dd8423091fe33ac4dd46deae8a7e320d59 Mon Sep 17 00:00:00 2001 From: Andrew Johnson Date: Thu, 19 Sep 2019 08:05:30 -0500 Subject: [PATCH 4/4] Apply suggestions from code review Co-Authored-By: Paul Romano --- docs/source/pythonapi/deplete.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/pythonapi/deplete.rst b/docs/source/pythonapi/deplete.rst index 55725f3bc..5a02e0794 100644 --- a/docs/source/pythonapi/deplete.rst +++ b/docs/source/pythonapi/deplete.rst @@ -51,14 +51,14 @@ specific to OpenMC is available using the following class: Operator The :class:`Operator` must also have some knowledge of how nuclides transmute -and decay. This is handled by the :class:`Chain` +and decay. This is handled by the :class:`Chain`. Minimal Example --------------- A minimal example for performing depletion would be: -.. code:: Python +.. code:: >>> import openmc >>> import openmc.deplete @@ -72,7 +72,7 @@ A minimal example for performing depletion would be: # Set up 5 time steps of one day each >>> dt = [24 * 60 * 60] * 5 - >>> power = 1E6 # constant power of 1 MW + >>> power = 1e6 # constant power of 1 MW # Deplete using mid-point predictor-corrector >>> cecm = openmc.deplete.CECMIntegrator(