diff --git a/docs/source/pythonapi/deplete.rst b/docs/source/pythonapi/deplete.rst index bc07ed1b0..9419244fe 100644 --- a/docs/source/pythonapi/deplete.rst +++ b/docs/source/pythonapi/deplete.rst @@ -12,20 +12,20 @@ Primary API The two primary requirements to perform depletion with :mod:`openmc.deplete` are: - 1) A reaction rate operator + 1) A depletion operator 2) A time-integration scheme -The former is responsible for obtaining transmuation reaction rates. 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:`CoupledOperator` class -is provided to obtain reaction rates via tallies through OpenMC's transport -solver, and the :class:`IndependentOperator` class is provided to obtain -reaction rates from cross-section data. 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 -`_. +The former is responsible for calcuating 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:`CoupledOperator` class is provided to obtain reaction rates via tallies +through OpenMC's transport solver, and the :class:`IndependentOperator` class is +provided to obtain reaction rates from cross-section data. 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 `_. .. autosummary:: :toctree: generated @@ -41,8 +41,8 @@ analysis of high order neutron transport-depletion coupling algorithms SICELIIntegrator SILEQIIntegrator -Each of these classes expects a "reaction rate operator" to be passed. Operators -provided by OpenMC are available using the following classes: +Each of these classes expects a "depletion operator" to be passed. OpenMC +provides The following classes implementing depletion operators: .. autosummary:: :toctree: generated @@ -214,7 +214,7 @@ are stored in :class:`helpers.TalliedFissionYieldHelper` helpers.TalliedFissionYieldHelper -Methods common to OpenMC-specific implementations of :class:`TransportOperator` +Methods common to OpenMC-specific implementations of :class:`DepletionOperator` are stored in :class:`openmc_operator.OpenMCOperator` .. autosummary:: @@ -230,19 +230,21 @@ 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 +inherit from :class:`abc.DepletionOperator` to implement alternative +schemes for collecting reaction rates and other data prior to depleting +materials .. autosummary:: :toctree: generated :nosignatures: :template: mycallable.rst - abc.TransportOperator + abc.DepletionOperator The following classes are abstract classes used to pass information from -OpenMC simulations back on to the :class:`abc.TransportOperator` +transport simulations (in the case of transport-coupled depletion) or to +simply calculate these quantities directly (in the case of +transport-independent depletion) back on to the :class:`abc.DepletionOperator` .. autosummary:: :toctree: generated diff --git a/docs/source/usersguide/depletion.rst b/docs/source/usersguide/depletion.rst index 990031c40..cc59efa6c 100644 --- a/docs/source/usersguide/depletion.rst +++ b/docs/source/usersguide/depletion.rst @@ -13,14 +13,14 @@ updated reaction rates, and the process is repeated for as many timesteps as are requested. The depletion module is designed such that the reaction rate solution (the -"operator") is completely isolated from the solution of the transmutation +depletion "operator") is completely isolated from the solution of the transmutation equations and the method used for advancing time. :mod:`openmc.deplete` supports multiple time-integration methods for determining material compositions over time. Each method appears as a different class. For example, :class:`openmc.deplete.CECMIntegrator` runs a depletion calculation using the CE/CM algorithm (deplete over a timestep using the middle-of-step -reaction rates). An instance of :class:`~openmc.deplete.abc.TransportOperator` +reaction rates). An instance of :class:`~openmc.deplete.abc.DepletionOperator` is passed to one of these functions along with the timesteps and power level:: power = 1200.0e6 # watts @@ -37,8 +37,8 @@ time:: time, keff = results.get_keff() Note that the coupling between the reaction rate solver and the transmutation -solver happens in-memory rather than by reading/writing files on disk. OpenMC has two categories of -operators for obtaining transmutation reaction rates. +solver happens in-memory rather than by reading/writing files on disk. OpenMC has two categories of depletion operators for obtaining transmutation reaction +rates. .. _coupled-depletion: diff --git a/openmc/deplete/abc.py b/openmc/deplete/abc.py index dd1fd5b04..e874479c0 100644 --- a/openmc/deplete/abc.py +++ b/openmc/deplete/abc.py @@ -28,8 +28,8 @@ from .pool import deplete __all__ = [ - "OperatorResult", "TransportOperator", "ReactionRateHelper", - "NormalizationHelper", "FissionYieldHelper", + "OperatorResult", "DepletionOperator", + "ReactionRateHelper", "NormalizationHelper", "FissionYieldHelper", "Integrator", "SIIntegrator", "DepSystemSolver", "add_params"] @@ -75,13 +75,13 @@ def change_directory(output_dir): os.chdir(orig_dir) -class TransportOperator(ABC): - """Abstract class defining a transport operator +class DepletionOperator(ABC): + """Abstract class defining a depletion operator - Each depletion integrator is written to work with a generic transport + Each depletion integrator is written to work with a generic depletion operator that takes a vector of material compositions and returns an eigenvalue and reaction rates. This abstract class sets the requirements - for such a transport operator. Users should instantiate + for such a depletion operator. Users should instantiate :class:`openmc.deplete.CoupledOperator` or :class:`openmc.deplete.IndependentOperator` rather than this class. @@ -222,10 +222,10 @@ class ReactionRateHelper(ABC): ---------- n_nucs : int Number of burnable nuclides tracked by - :class:`openmc.deplete.abc.TransportOperator` + :class:`openmc.deplete.abc.DepletionOperator` n_react : int Number of reactions tracked by - :class:`openmc.deplete.abc.TransportOperator` + :class:`openmc.deplete.abc.DepletionOperator` Attributes ---------- @@ -294,7 +294,7 @@ class NormalizationHelper(ABC): """Abstract class for obtaining normalization factor on tallies This helper class determines how reaction rates calculated by an instance of - :class:`openmc.deplete.abc.TransportOperator` should be normalized for the + :class:`openmc.deplete.abc.DepletionOperator` should be normalized for the purpose of constructing a burnup matrix. Based on the method chosen, the power or source rate provided by the user, and reaction rates from a :class:`ReactionRateHelper`, this class will scale reaction rates to the @@ -304,7 +304,7 @@ class NormalizationHelper(ABC): ---------- nuclides : list of str All nuclides with desired reaction rates. Ordered to be - consistent with :class:`openmc.deplete.abc.TransportOperator` + consistent with :class:`openmc.deplete.abc.DepletionOperator` """ @@ -319,7 +319,7 @@ class NormalizationHelper(ABC): """Perform work needed to obtain energy produced This method is called prior to calculating the reaction rates - in :meth:`openmc.deplete.abc.TransportOperator.initial_condition`. Only + in :meth:`openmc.deplete.abc.DepletionOperator.initial_condition`. Only used for energy-based normalization. Parameters @@ -433,7 +433,7 @@ class FissionYieldHelper(ABC): def unpack(): """Unpack tally data prior to compute fission yields. - Called after a :meth:`openmc.deplete.abc.TransportOperator.__call__` + Called after a :meth:`openmc.deplete.abc.DepletionOperator.__call__` routine during the normalization of reaction rates. Not necessary for all subclasses to implement, unless tallies @@ -466,13 +466,13 @@ class FissionYieldHelper(ABC): ---------- nuclides : iterable of str Nuclides with non-zero densities from the - :class:`openmc.deplete.abc.TransportOperator` + :class:`openmc.deplete.abc.DepletionOperator` Returns ------- nuclides : list of str Union of nuclides that the - :class:`openmc.deplete.abc.TransportOperator` says have non-zero + :class:`openmc.deplete.abc.DepletionOperator` says have non-zero densities at this stage and those that have yield data. Sorted by nuclide name @@ -488,7 +488,7 @@ class FissionYieldHelper(ABC): Parameters ---------- - operator : openmc.deplete.abc.TransportOperator + operator : openmc.deplete.abc.DepletionOperator Operator with a depletion chain kwargs: optional Additional keyword arguments to be used in constuction @@ -509,8 +509,8 @@ class Integrator(ABC): _params = r""" Parameters ---------- - operator : openmc.deplete.abc.TransportOperator - Operator to perform transport simulations + operator : openmc.deplete.abc.DepletionOperator + Operator that calculates reaction rates timesteps : iterable of float or iterable of tuple Array of timesteps. Note that values are not cumulative. The units are specified by the `timestep_units` argument when `timesteps` is an @@ -552,8 +552,8 @@ class Integrator(ABC): Attributes ---------- - operator : openmc.deplete.abc.TransportOperator - Operator to perform transport simulations + operator : openmc.deplete.abc.DepletionOperator + Operator that calculates reaction rates chain : openmc.deplete.Chain Depletion chain timesteps : iterable of float @@ -847,8 +847,8 @@ class SIIntegrator(Integrator): _params = r""" Parameters ---------- - operator : openmc.deplete.abc.TransportOperator - The operator object to simulate on. + operator : openmc.deplete.abc.DepletionOperator + Operator that calculates reaction rates timesteps : iterable of float or iterable of tuple Array of timesteps. Note that values are not cumulative. The units are specified by the `timestep_units` argument when `timesteps` is an @@ -893,8 +893,8 @@ class SIIntegrator(Integrator): Attributes ---------- - operator : openmc.deplete.abc.TransportOperator - Operator to perform transport simulations + operator : openmc.deplete.abc.DepletionOperator + Operator that calculates reaction rates chain : openmc.deplete.Chain Depletion chain timesteps : iterable of float diff --git a/openmc/deplete/coupled_operator.py b/openmc/deplete/coupled_operator.py index 35b63e9cf..39e46c882 100644 --- a/openmc/deplete/coupled_operator.py +++ b/openmc/deplete/coupled_operator.py @@ -1,7 +1,8 @@ """Transport-coupled operator for depletion. -This module implements an operator coupled to OpenMC's transport sovler so that -it can be used by depletion integrators. The implementation makes use of the Python bindings to OpenMC's C API so that reading tally results and updating +This module implements a depletion operator coupled to OpenMC's transport solver +so that it can be used by depletion integrators. The implementation makes use of +the Python bindings to OpenMC's C API so that reading tally results and updating material number densities is all done in-memory instead of through the filesystem. @@ -57,7 +58,7 @@ def _find_cross_sections(model): class CoupledOperator(OpenMCOperator): - """Transport-coupled operator for depletion. + """Transport-coupled depletion operator. Instances of this class can be used to perform transport-coupled depletion using OpenMC's transport solver. Normally, a user needn't call methods of diff --git a/openmc/deplete/helpers.py b/openmc/deplete/helpers.py index 262e61b35..77f3da201 100644 --- a/openmc/deplete/helpers.py +++ b/openmc/deplete/helpers.py @@ -557,7 +557,7 @@ class ConstantFissionYieldHelper(FissionYieldHelper): Parameters ---------- - operator : openmc.deplete.TransportOperator + operator : openmc.deplete.abc.DepletionOperator operator with a depletion chain kwargs: Additional keyword arguments to be used in construction diff --git a/openmc/deplete/independent_operator.py b/openmc/deplete/independent_operator.py index a7eb54f57..631117403 100644 --- a/openmc/deplete/independent_operator.py +++ b/openmc/deplete/independent_operator.py @@ -1,4 +1,4 @@ -"""Transport-independent operator for depletion. +"""Transport-independent depletion operator. This module implements a depletion operator that runs independently of any transport solver by using user-provided one-group cross sections. @@ -23,8 +23,8 @@ from .results import Results from .helpers import ChainFissionHelper, ConstantFissionYieldHelper, SourceRateHelper class IndependentOperator(OpenMCOperator): - """Depletion operator that uses one-group cross sections to calculate - reaction rates. + """Transport-independent depletion operator that uses one-group cross + sections to calculate reaction rates. Instances of this class can be used to perform depletion using one-group cross sections and constant flux or constant power. Normally, a user needn't @@ -189,7 +189,8 @@ class IndependentOperator(OpenMCOperator): if ``reduce_chain`` evaluates to true. The default value of ``None`` implies no limit on the depth. fission_yield_opts : dict of str to option, optional - Optional arguments to pass to the `FissionYieldHelper`. Will be + Optional arguments to pass to the + :class:`openmc.deplete.helpers.FissionYieldHelper` class. Will be passed directly on to the helper. Passing a value of None will use the defaults for the associated helper. diff --git a/openmc/deplete/openmc_operator.py b/openmc/deplete/openmc_operator.py index 7235ab9bf..bcf73a010 100644 --- a/openmc/deplete/openmc_operator.py +++ b/openmc/deplete/openmc_operator.py @@ -1,6 +1,7 @@ """OpenMC transport operator -This module implements functions shared by both OpenMC transport operators as well as indepenedent depletion operators. +This module implements functions shared by both OpenMC transport-coupled and +transport-independent depletion operators. """ @@ -11,7 +12,7 @@ import numpy as np import openmc from openmc.mpi import comm -from .abc import TransportOperator, OperatorResult +from .abc import DepletionOperator, OperatorResult from .atom_number import AtomNumber from .reaction_rates import ReactionRates @@ -41,12 +42,12 @@ def _distribute(items): j += chunk_size -class OpenMCOperator(TransportOperator): +class OpenMCOperator(DepletionOperator): """Abstract class holding OpenMC-specific functions for running depletion calculations. - Specific classes for running coupled transport-depletion calculations or - depletion-only calculations are implemented as subclasses of OpenMCOperator + Specific classes for running transport-coupled or transport-independent + depletion calculations are implemented as subclasses of OpenMCOperator. Parameters ---------- diff --git a/openmc/deplete/stepresult.py b/openmc/deplete/stepresult.py index 80a664c6f..3082cf304 100644 --- a/openmc/deplete/stepresult.py +++ b/openmc/deplete/stepresult.py @@ -462,7 +462,7 @@ class StepResult: Parameters ---------- - op : openmc.deplete.TransportOperator + op : openmc.deplete.abc.DepletionOperator The operator used to generate these results. x : list of list of numpy.array The prior x vectors. Indexed [i][cell] using the above equation. diff --git a/tests/dummy_operator.py b/tests/dummy_operator.py index 1bb00129d..c54269cc0 100644 --- a/tests/dummy_operator.py +++ b/tests/dummy_operator.py @@ -6,7 +6,7 @@ import scipy.sparse as sp from uncertainties import ufloat from openmc.deplete.reaction_rates import ReactionRates -from openmc.deplete.abc import TransportOperator, OperatorResult +from openmc.deplete.abc import DepletionOperator, OperatorResult from openmc.deplete import ( CECMIntegrator, PredictorIntegrator, CELIIntegrator, LEQIIntegrator, EPCRK4Integrator, CF4Integrator, SICELIIntegrator, SILEQIIntegrator @@ -117,7 +117,7 @@ class TestChain: return sp.csr_matrix(np.array([[a11, a12], [a21, a22]])) -class DummyOperator(TransportOperator): +class DummyOperator(DepletionOperator): """This is a dummy operator class with no statistical uncertainty. y_1' = sin(y_2) y_1 + cos(y_1) y_2 diff --git a/tests/unit_tests/test_deplete_operator.py b/tests/unit_tests/test_deplete_operator.py index 5fe8715ac..1910112b8 100644 --- a/tests/unit_tests/test_deplete_operator.py +++ b/tests/unit_tests/test_deplete_operator.py @@ -7,7 +7,7 @@ to a custom file with new depletion_chain node from pathlib import Path import pytest -from openmc.deplete.abc import TransportOperator +from openmc.deplete.abc import DepletionOperator from openmc.deplete.chain import Chain, _find_chain_file BARE_XS_FILE = "bare_cross_sections.xml" @@ -32,7 +32,7 @@ def bare_xs(run_in_tmpdir): yield BARE_XS_FILE -class BareDepleteOperator(TransportOperator): +class BareDepleteOperator(DepletionOperator): """Very basic class for testing the initialization.""" @staticmethod