Repository: terrapower/armi
Pull request #1508 (2023-11-29 21:53:45)

Adding some impl crumbs to docstrings
## What is the change?

Adding some impl crumbs to docstrings.

---

## Checklist

- [X] This PR has only [one purpose or idea](https://terrapower.github.io/armi/developer/tooling.html#one-idea-one-pr).
- [X] [Tests](https://terrapower.github.io/armi/developer/tooling.html#test-it) have been added/updated to verify that the new/changed code works.

<!-- Check the code quality -->

- [X] The code style follows [good practices](https://terrapower.github.io/armi/developer/standards_and_practices.html).
- [X] The commit message(s) follow [good practices](https://terrapower.github.io/armi/developer/tooling.html).

<!-- Check the project-level cruft -->

- [X] The [release notes](https://terrapower.github.io/armi/release/index.html) (location `doc/release/0.X.rst`) are up-to-date with any important changes.
- [X] The [documentation](https://terrapower.github.io/armi/developer/tooling.html#document-it) is still up-to-date in the `doc` folder.
- [ ] No [requirements](https://terrapower.github.io/armi/developer/tooling.html#watch-for-requirements) were altered.
- [X] The dependencies are still up-to-date in `pyproject.toml`.



Patch:
diff --git a/armi/nuclearDataIO/xsCollections.py b/armi/nuclearDataIO/xsCollections.py
index 3f135756..e453a016 100644
--- a/armi/nuclearDataIO/xsCollections.py
+++ b/armi/nuclearDataIO/xsCollections.py
@@ -381,6 +381,7 @@ class MacroscopicCrossSectionCreator:
     def createMacrosOnBlocklist(
         self, microLibrary, blockList, nucNames=None, libType="micros"
     ):
+        """Create macroscopic cross sections for a list of blocks."""
         for block in blockList:
             block.macros = self.createMacrosFromMicros(
                 microLibrary, block, nucNames, libType=libType
@@ -788,6 +789,10 @@ def computeMacroscopicGroupConstants(
     """
     Compute any macroscopic group constants given number densities and a microscopic library.
 
+    .. impl:: Compute macroscopic cross sections from microscopic cross sections and number densities.
+        :id: I_ARMI_NUCDATA_MACRO
+        :implements: R_ARMI_NUCDATA_MACRO
+
     Parameters
     ----------
     constantName : str
diff --git a/armi/physics/neutronics/energyGroups.py b/armi/physics/neutronics/energyGroups.py
index 5ecda047..3f430326 100644
--- a/armi/physics/neutronics/energyGroups.py
+++ b/armi/physics/neutronics/energyGroups.py
@@ -30,7 +30,12 @@ from armi.physics.neutronics.const import (
 
 
 def getFastFluxGroupCutoff(eGrpStruc):
-    """Given a constant "fast" energy threshold, return which ARMI energy group index contains this threshold."""
+    """Given a constant "fast" energy threshold, return which ARMI energy group index contains this threshold.
+
+    .. impl:: Return the energy group index which contains a given energy threshold.
+        :id: I_ARMI_EG_FE
+        :implements: R_ARMI_EG_FE
+    """
     gThres = -1
     for g, eV in enumerate(eGrpStruc):
         if eV < FAST_FLUX_THRESHOLD_EV:
@@ -67,6 +72,10 @@ def getGroupStructure(name):
     """
     Return descending neutron energy group upper bounds in eV for a given structure name.
 
+    .. impl:: Provide the neutron energy group bounds for a given group structure.
+        :id: I_ARMI_EG_NE
+        :implements: R_ARMI_EG_NE
+
     Notes
     -----
     Copy of the group structure is return so that modifications of the energy bounds does
diff --git a/armi/physics/neutronics/globalFlux/globalFluxInterface.py b/armi/physics/neutronics/globalFlux/globalFluxInterface.py
index d4ace8ff..8f4a293d 100644
--- a/armi/physics/neutronics/globalFlux/globalFluxInterface.py
+++ b/armi/physics/neutronics/globalFlux/globalFluxInterface.py
@@ -119,8 +119,13 @@ class GlobalFluxInterface(interfaces.Interface):
                 * units.ABS_REACTIVITY_TO_PCM
             )
 
-    def _checkEnergyBalance(self):
-        """Check that there is energy balance between the power generated and the specified power is the system."""
+    def checkEnergyBalance(self):
+        """Check that there is energy balance between the power generated and the specified power.
+
+        .. impl:: Validate the energy generate matches user specifications.
+            :id: I_ARMI_FLUX_CHECK_POWER
+            :implements: R_ARMI_FLUX_CHECK_POWER
+        """
         powerGenerated = (
             self.r.core.calcTotalParam(
                 "power", calcBasedOnFullObj=False, generationNum=2
diff --git a/armi/physics/neutronics/macroXSGenerationInterface.py b/armi/physics/neutronics/macroXSGenerationInterface.py
index 0303cb92..1a69f55c 100644
--- a/armi/physics/neutronics/macroXSGenerationInterface.py
+++ b/armi/physics/neutronics/macroXSGenerationInterface.py
@@ -144,6 +144,10 @@ class MacroXSGenerationInterface(interfaces.Interface):
         Builds G-vectors of the basic XS ('nGamma','fission','nalph','np','n2n','nd','nt')
         Builds GxG matrices for scatter matrices
 
+        .. impl:: Build macroscopic cross sections for blocks.
+            :id: I_ARMI_MACRO_XS
+            :implements: R_ARMI_MACRO_XS
+
         Parameters
         ----------
         lib : library object , optional
diff --git a/armi/reactor/assemblies.py b/armi/reactor/assemblies.py
index bff1866e..66e3c145 100644
--- a/armi/reactor/assemblies.py
+++ b/armi/reactor/assemblies.py
@@ -180,7 +180,6 @@ class Assembly(composites.Composite):
         .. impl:: Assemblies are made up of type Block.
             :id: I_ARMI_ASSEM_BLOCKS
             :implements: R_ARMI_ASSEM_BLOCKS
-
         """
         composites.Composite.add(self, obj)
         obj.spatialLocator = self.spatialGrid[0, 0, len(self) - 1]
@@ -227,7 +226,6 @@ class Assembly(composites.Composite):
         .. impl:: Assembly location is retrievable.
             :id: I_ARMI_ASSEM_POSI0
             :implements: R_ARMI_ASSEM_POSI
-
         """
         # just use ring and position, not axial (which is 0)
         if not self.parent:
@@ -1229,6 +1227,13 @@ class Assembly(composites.Composite):
 
 
 class HexAssembly(Assembly):
+    """Placeholder, so users can explicitly define a hex-based assembly.
+
+    .. impl:: Assembly of hex blocks.
+        :id: I_ARMI_ASSEM_HEX
+        :implements: R_ARMI_ASSEM_HEX
+    """
+
     pass
 
 
diff --git a/armi/reactor/blocks.py b/armi/reactor/blocks.py
index dbab8b45..4d83e827 100644
--- a/armi/reactor/blocks.py
+++ b/armi/reactor/blocks.py
@@ -1561,6 +1561,10 @@ class Block(composites.Composite):
     def setAxialExpTargetComp(self, targetComponent):
         """Sets the targetComponent for the axial expansion changer.
 
+        .. impl:: Set the target axial expansion components on a given block.
+            :id: I_ARMI_MANUAL_TARG_COMP
+            :implements: R_ARMI_MANUAL_TARG_COMP
+
         Parameter
         ---------
         targetComponent: :py:class:`Component <armi.reactor.components.component.Component>` object
diff --git a/armi/reactor/blueprints/componentBlueprint.py b/armi/reactor/blueprints/componentBlueprint.py
index 24422951..f37e2f8a 100644
--- a/armi/reactor/blueprints/componentBlueprint.py
+++ b/armi/reactor/blueprints/componentBlueprint.py
@@ -291,6 +291,10 @@ def insertDepletableNuclideKeys(c, blueprint):
     """
     Auto update number density keys on all DEPLETABLE components.
 
+    .. impl:: Insert any depletable blueprint flags onto this component.
+        :id: I_ARMI_BP_NUC_FLAGS0
+        :implements: R_ARMI_BP_NUC_FLAGS
+
     Notes
     -----
     This should be moved to a neutronics/depletion plugin hook but requires some
diff --git a/armi/reactor/blueprints/isotopicOptions.py b/armi/reactor/blueprints/isotopicOptions.py
index 0e37b4cf..ead85253 100644
--- a/armi/reactor/blueprints/isotopicOptions.py
+++ b/armi/reactor/blueprints/isotopicOptions.py
@@ -61,6 +61,10 @@ class NuclideFlag(yamlize.Object):
     physics option. However, restarting from that case with different
     cross section needs is challenging.
 
+    .. impl:: The blueprint object that represents a nuclide flag.
+        :id: I_ARMI_BP_NUC_FLAGS1
+        :implements: R_ARMI_BP_NUC_FLAGS
+
     Attributes
     ----------
     nuclideName : str
diff --git a/armi/reactor/converters/axialExpansionChanger.py b/armi/reactor/converters/axialExpansionChanger.py
index aed69854..3b5f391b 100644
--- a/armi/reactor/converters/axialExpansionChanger.py
+++ b/armi/reactor/converters/axialExpansionChanger.py
@@ -114,6 +114,10 @@ class AxialExpansionChanger:
         :id: I_ARMI_AXIAL_EXP
         :implements: R_ARMI_AXIAL_EXP
 
+    .. impl:: Preserve the total height of an ARMI assembly, during expansion.
+        :id: I_ARMI_ASSEM_HEIGHT_PRES
+        :implements: R_ARMI_ASSEM_HEIGHT_PRES
+
     Attributes
     ----------
     linked : :py:class:`AssemblyAxialLinkage`
diff --git a/armi/reactor/converters/geometryConverters.py b/armi/reactor/converters/geometryConverters.py
index e9b8777c..418f320a 100644
--- a/armi/reactor/converters/geometryConverters.py
+++ b/armi/reactor/converters/geometryConverters.py
@@ -1194,11 +1194,15 @@ class HexToRZThetaConverter(GeometryConverter):
 
 
 class HexToRZConverter(HexToRZThetaConverter):
-    r"""
+    """
     Create a new reactor with R-Z coordinates from the Hexagonal-Z reactor.
 
-    This is a subclass of the HexToRZThetaConverter. See the HexToRZThetaConverter for explanation and setup of
-    the converterSettings.
+    This is a subclass of the HexToRZThetaConverter. See the HexToRZThetaConverter for
+    explanation and setup of the converterSettings.
+
+    .. impl:: Tool to convert a hex core to an RZTheta core.
+        :id: I_ARMI_CONV_3DHEX_TO_2DRZ
+        :implements: R_ARMI_CONV_3DHEX_TO_2DRZ
     """
 
     _GEOMETRY_TYPE = geometry.GeomType.RZ
diff --git a/armi/reactor/grids/structuredgrid.py b/armi/reactor/grids/structuredgrid.py
index 7b74eaad..f37c9543 100644
--- a/armi/reactor/grids/structuredgrid.py
+++ b/armi/reactor/grids/structuredgrid.py
@@ -292,9 +292,9 @@ class StructuredGrid(Grid):
     def getCoordinates(self, indices, nativeCoords=False) -> numpy.ndarray:
         """Return the coordinates of the center of the mesh cell at the given indices in cm.
 
-        .. test:: Get the coordinates from a location in a grid.
+        .. impl:: Get the coordinates from a location in a grid.
             :id: I_ARMI_GRID_GLOBAL_POS
-            :tests: R_ARMI_GRID_GLOBAL_POS
+            :implements: R_ARMI_GRID_GLOBAL_POS
         """
         indices = numpy.array(indices)
         return self._evaluateMesh(


Test patch:
diff --git a/armi/physics/neutronics/globalFlux/tests/test_globalFluxInterface.py b/armi/physics/neutronics/globalFlux/tests/test_globalFluxInterface.py
index a7726ba2..2fd627a3 100644
--- a/armi/physics/neutronics/globalFlux/tests/test_globalFluxInterface.py
+++ b/armi/physics/neutronics/globalFlux/tests/test_globalFluxInterface.py
@@ -180,8 +180,7 @@ class TestGlobalFluxInterface(unittest.TestCase):
         self.assertIn("detailedDpa", params)
 
     def test_checkEnergyBalance(self):
-        """
-        Test energy balance check.
+        """Test energy balance check.
 
         .. test:: Block-wise power is consistent with reactor data model power.
             :id: T_ARMI_FLUX_CHECK_POWER
@@ -190,7 +189,7 @@ class TestGlobalFluxInterface(unittest.TestCase):
         cs = settings.Settings()
         _o, r = test_reactors.loadTestReactor()
         gfi = MockGlobalFluxInterface(r, cs)
-        gfi._checkEnergyBalance()
+        gfi.checkEnergyBalance()
 
 
 class TestGlobalFluxInterfaceWithExecuters(unittest.TestCase):
diff --git a/armi/physics/neutronics/tests/test_energyGroups.py b/armi/physics/neutronics/tests/test_energyGroups.py
index 23f7d903..6cb2b967 100644
--- a/armi/physics/neutronics/tests/test_energyGroups.py
+++ b/armi/physics/neutronics/tests/test_energyGroups.py
@@ -20,7 +20,12 @@ from armi.physics.neutronics import energyGroups
 
 class TestEnergyGroups(unittest.TestCase):
     def test_invalidGroupStructureType(self):
-        """Test that the reverse lookup fails on non-existent energy group bounds."""
+        """Test that the reverse lookup fails on non-existent energy group bounds.
+
+        .. test:: Check the neutron energy group bounds logic fails correctly for the wrong structure.
+            :id: T_ARMI_EG_NE0
+            :tests: R_ARMI_EG_NE
+        """
         modifier = 1e-5
         for groupStructureType in energyGroups.GROUP_STRUCTURE:
             energyBounds = energyGroups.getGroupStructure(groupStructureType)
@@ -32,6 +37,10 @@ class TestEnergyGroups(unittest.TestCase):
         """
         Test that the reverse lookup of the energy group structures work.
 
+        .. test:: Check the neutron energy group bounds for a given group structure.
+            :id: T_ARMI_EG_NE1
+            :tests: R_ARMI_EG_NE
+
         Notes
         -----
         Several group structures point to the same energy group structure so the reverse lookup will fail to
diff --git a/armi/reactor/blueprints/tests/test_blockBlueprints.py b/armi/reactor/blueprints/tests/test_blockBlueprints.py
index cbab444f..a06964b5 100644
--- a/armi/reactor/blueprints/tests/test_blockBlueprints.py
+++ b/armi/reactor/blueprints/tests/test_blockBlueprints.py
@@ -310,7 +310,7 @@ class TestGriddedBlock(unittest.TestCase):
         Test flags are created from blueprint file.
 
         .. test:: Nuc flags can define depletable objects.
-            :id: T_ARMI_BP_NUC_FLAGS
+            :id: T_ARMI_BP_NUC_FLAGS0
             :tests: R_ARMI_BP_NUC_FLAGS
         """
         a1 = self.blueprints.assemDesigns.bySpecifier["IC"].construct(
diff --git a/armi/reactor/blueprints/tests/test_blueprints.py b/armi/reactor/blueprints/tests/test_blueprints.py
index 9661ad82..a96fcead 100644
--- a/armi/reactor/blueprints/tests/test_blueprints.py
+++ b/armi/reactor/blueprints/tests/test_blueprints.py
@@ -102,7 +102,12 @@ class TestBlueprints(unittest.TestCase):
         self.assertAlmostEqual(fuel.getDimension("mult"), 169)
 
     def test_traceNuclides(self):
-        """Ensure that armi.reactor.blueprints.componentBlueprint.insertDepletableNuclideKeys runs."""
+        """Ensure that armi.reactor.blueprints.componentBlueprint.insertDepletableNuclideKeys runs.
+
+        .. test:: Users marking components as depletable will affect number densities.
+            :id: T_ARMI_BP_NUC_FLAGS1
+            :tests: R_ARMI_BP_NUC_FLAGS
+        """
         fuel = (
             self.blueprints.constructAssem(self.cs, "igniter fuel")
             .getFirstBlock(Flags.FUEL)
diff --git a/armi/reactor/converters/tests/test_geometryConverters.py b/armi/reactor/converters/tests/test_geometryConverters.py
index f704262b..5a1b52c9 100644
--- a/armi/reactor/converters/tests/test_geometryConverters.py
+++ b/armi/reactor/converters/tests/test_geometryConverters.py
@@ -40,7 +40,7 @@ class TestGeometryConverters(unittest.TestCase):
         self.cs = self.o.cs
 
     def test_addRing(self):
-        r"""Tests that the addRing method adds the correct number of fuel assemblies to the test reactor."""
+        """Tests that the addRing method adds the correct number of fuel assemblies to the test reactor."""
         converter = geometryConverters.FuelAssemNumModifier(self.cs)
         converter.numFuelAssems = 7
         converter.ringsToAdd = 1 * ["radial shield"]
@@ -65,7 +65,7 @@ class TestGeometryConverters(unittest.TestCase):
         )  # should wind up with 11 reflector assemblies per 1/3rd core
 
     def test_setNumberOfFuelAssems(self):
-        r"""Tests that the setNumberOfFuelAssems method properly changes the number of fuel assemblies."""
+        """Tests that the setNumberOfFuelAssems method properly changes the number of fuel assemblies."""
         # tests ability to add fuel assemblies
         converter = geometryConverters.FuelAssemNumModifier(self.cs)
         converter.numFuelAssems = 60
@@ -142,6 +142,12 @@ class TestHexToRZConverter(unittest.TestCase):
         del self.r
 
     def test_convert(self):
+        """Test the HexToRZConverter.
+
+        .. test:: Convert a 3D hex reactor core to an RZ-Theta core.
+            :id: T_ARMI_CONV_3DHEX_TO_2DRZ
+            :tests: R_ARMI_CONV_3DHEX_TO_2DRZ
+        """
         # make the reactor smaller, because of a test parallelization edge case
         for ring in [9, 8, 7, 6, 5, 4, 3]:
             self.r.core.removeAssembliesInRing(ring, self.o.cs)