Adding impl/test crumbs for nucDir (#1482)

Author: john-science

armi/nucDirectory/elements.py

@@ -16,6 +16,10 @@
 This module provides fundamental element information to be used throughout the framework
 and applications.
 
+.. impl:: A tool for querying basic data for elements of the periodic table.
+    :id: I_ARMI_ND_ELEMENTS0
+    :implements: R_ARMI_ND_ELEMENTS
+
 The element class structure is outlined :ref:`here <elements-class-diagram>`.
 
 .. _elements-class-diagram:
@@ -149,6 +153,10 @@ def __init__(self, z, symbol, name, phase="UNKNOWN", group="UNKNOWN"):
         """
         Creates an instance of an Element.
 
+        .. impl:: An element of the periodic table.
+            :id: I_ARMI_ND_ELEMENTS1
+            :implements: R_ARMI_ND_ELEMENTS
+
         Parameters
         ----------
         z : int

armi/nucDirectory/nuclideBases.py

@@ -15,6 +15,10 @@
 This module provides fundamental nuclide information to be used throughout the framework
 and applications.
 
+.. impl:: Isotopes and isomers can be queried by name, label, MC2-3 ID, MCNP ID, and AAAZZZS ID.
+    :id: I_ARMI_ND_ISOTOPES0
+    :implements: R_ARMI_ND_ISOTOPES
+
 The nuclide class structure is outlined :ref:`here <nuclide-bases-class-diagram>`.
 
 .. _nuclide-bases-class-diagram:
@@ -423,7 +427,7 @@ def _processBurnData(self, burnInfo):
                 )
 
     def getDecay(self, decayType):
-        r"""Get a :py:class:`~armi.nucDirectory.transmutations.DecayMode`.
+        """Get a :py:class:`~armi.nucDirectory.transmutations.DecayMode`.
 
         Retrieve the first :py:class:`~armi.nucDirectory.transmutations.DecayMode`
         matching the specified decType.
@@ -493,7 +497,12 @@ def getAAAZZZSId(self):
 
 
 class NuclideBase(INuclide, IMcnpNuclide):
-    """Represents an individual nuclide/isotope."""
+    """Represents an individual nuclide/isotope.
+
+    .. impl:: Isotopes and isomers can be queried by name and label.
+        :id: I_ARMI_ND_ISOTOPES1
+        :implements: R_ARMI_ND_ISOTOPES
+    """
 
     def __init__(self, element, a, weight, abundance, state, halflife):
         IMcnpNuclide.__init__(self)
@@ -558,22 +567,35 @@ def getNaturalIsotopics(self):
         return self.element.getNaturalIsotopics()
 
     def getMcc2Id(self):
-        """Return the MC2-2 nuclide identification label based on the ENDF/B-V.2 cross section library."""
+        """Return the MC2-2 nuclide identification label based on the ENDF/B-V.2 cross section library.
+
+        .. impl:: Isotopes and isomers can be queried by MC2-2 ID.
+            :id: I_ARMI_ND_ISOTOPES2
+            :implements: R_ARMI_ND_ISOTOPES
+        """
         return self.mcc2id
 
     def getMcc3Id(self):
-        """Return the MC2-3 nuclide identification label based on the ENDF/B-VII.0 cross section library."""
+        """Return the MC2-3 nuclide identification label based on the ENDF/B-VII.0 cross section library.
+
+        .. impl:: Isotopes and isomers can be queried by MC2-3 ID.
+            :id: I_ARMI_ND_ISOTOPES3
+            :implements: R_ARMI_ND_ISOTOPES
+        """
         return self.mcc3id
 
     def getMcnpId(self):
         """
         Gets the MCNP label for this nuclide.
 
+        .. impl:: Isotopes and isomers can be queried by MCNP ID.
+            :id: I_ARMI_ND_ISOTOPES4
+            :implements: R_ARMI_ND_ISOTOPES
+
         Returns
         -------
         id : str
             The MCNP ID e.g. ``92235``, ``94239``, ``6000``
-
         """
         z, a = self.z, self.a
 
@@ -595,6 +617,10 @@ def getAAAZZZSId(self):
         """
         Return a string that is ordered by the mass number, A, the atomic number, Z, and the isomeric state, S.
 
+        .. impl:: Isotopes and isomers can be queried by AAAZZZS ID.
+            :id: I_ARMI_ND_ISOTOPES5
+            :implements: R_ARMI_ND_ISOTOPES
+
         Notes
         -----
         An example would be for U235, where A=235, Z=92, and S=0, returning ``2350920``.
@@ -629,7 +655,6 @@ def getEndfMatNum(self):
         -------
         id : str
             The MAT number e.g. ``9237`` for U238
-
         """
         z, a = self.z, self.a
         if self.element.symbol in BASE_ENDFB7_MAT_NUM:
@@ -679,7 +704,7 @@ def __repr__(self):
         return f"<{self.__class__.__name__} {self.name}:  Z:{self.z}, W:{self.weight:<12.6e}, Label:{self.label}>"
 
     def getNaturalIsotopics(self):
-        r"""Gets the natural isotopics root :py:class:`~elements.Element`.
+        """Gets the natural isotopics root :py:class:`~elements.Element`.
 
         Gets the naturally occurring nuclides for this nuclide.
 
@@ -789,7 +814,7 @@ def __lt__(self, other):
         )
 
     def getNaturalIsotopics(self):
-        r"""Gets the natural isotopics, an empty iterator.
+        """Gets the natural isotopics, an empty iterator.
 
         Gets the naturally occurring nuclides for this nuclide.
 
@@ -855,7 +880,7 @@ def __lt__(self, other):
         )
 
     def getNaturalIsotopics(self):
-        r"""Gets the natural isotopics, an empty iterator.
+        """Gets the natural isotopics, an empty iterator.
 
         Gets the naturally occurring nuclides for this nuclide.
 
@@ -1115,12 +1140,12 @@ def factory():
             "Nuclides are already initialized and cannot be re-initialized unless "
             "`nuclideBases.destroyGlobalNuclides` is called first."
         )
-    __addNuclideBases()
+    addNuclideBases()
     __addNaturalNuclideBases()
     __addDummyNuclideBases()
     __addLumpedFissionProductNuclideBases()
-    __updateNuclideBasesForSpecialCases()
-    __readMCCNuclideData()
+    updateNuclideBasesForSpecialCases()
+    readMCCNuclideData()
     __renormalizeNuclideToElementRelationship()
     __deriveElementalWeightsByNaturalNuclideAbundances()
 
@@ -1130,11 +1155,15 @@ def factory():
     thermalScattering.factory()
 
 
-def __addNuclideBases():
+def addNuclideBases():
     """
     Read natural abundances of any natural nuclides.
 
     This adjusts already-existing NuclideBases and Elements with the new information.
+
+    .. impl:: Separating natural abundance data from code.
+        :id: I_ARMI_ND_DATA0
+        :implements: R_ARMI_ND_DATA
     """
     with open(os.path.join(context.RES, "nuclides.dat")) as f:
         for line in f:
@@ -1190,8 +1219,13 @@ def __addLumpedFissionProductNuclideBases():
     LumpNuclideBase(name="LREGN", weight=1.0)
 
 
-def __readMCCNuclideData():
-    """Read in the label data for the MC2-2 and MC2-3 cross section codes to the nuclide bases."""
+def readMCCNuclideData():
+    """Read in the label data for the MC2-2 and MC2-3 cross section codes to the nuclide bases.
+
+    .. impl:: Separating MCC data from code.
+        :id: I_ARMI_ND_DATA1
+        :implements: R_ARMI_ND_DATA
+    """
     with open(os.path.join(context.RES, "mcc-nuclides.yaml"), "r") as f:
         yaml = YAML(typ="rt")
         nuclides = yaml.load(f)
@@ -1208,10 +1242,14 @@ def __readMCCNuclideData():
             byMcc3Id[nb.getMcc3Id()] = nb
 
 
-def __updateNuclideBasesForSpecialCases():
+def updateNuclideBasesForSpecialCases():
     """
     Update the nuclide bases for special case name changes.
 
+    .. impl:: The special case name Am242g is supported.
+        :id: I_ARMI_ND_ISOTOPES6
+        :implements: R_ARMI_ND_ISOTOPES
+
     Notes
     -----
     This function is specifically added to change the definition of

armi/nucDirectory/tests/test_elements.py

@@ -35,14 +35,32 @@ def test_elements_elementBulkProperties(self):
             self.assertIsNotNone(ee.standardWeight)
 
     def test_element_elementByNameReturnsElement(self):
+        """Get elements by name.
+
+        .. test:: Get elements by name.
+            :id: I_ARMI_ND_ELEMENTS0
+            :tests: R_ARMI_ND_ELEMENTS
+        """
         for ee in elements.byZ.values():
             self.assertIs(ee, elements.byName[ee.name])
 
     def test_element_elementByZReturnsElement(self):
+        """Get elements by Z.
+
+        .. test:: Get elements by Z.
+            :id: I_ARMI_ND_ELEMENTS1
+            :tests: R_ARMI_ND_ELEMENTS
+        """
         for ee in elements.byZ.values():
             self.assertIs(ee, elements.byZ[ee.z])
 
     def test_element_elementBySymbolReturnsElement(self):
+        """Get elements by symbol.
+
+        .. test:: Get elements by symbol.
+            :id: I_ARMI_ND_ELEMENTS2
+            :tests: R_ARMI_ND_ELEMENTS
+        """
         for ee in elements.byZ.values():
             self.assertIs(ee, elements.bySymbol[ee.symbol])
 
@@ -84,6 +102,10 @@ def test_element_isNaturallyOccurring(self):
 
         Uses RIPL definitions of naturally occurring. Protactinium is debated as naturally
         occurring. Yeah it exists as a U235 decay product but it's kind of pseudo-natural.
+
+        .. test:: Get elements by Z, to show if they are naturally occurring.
+            :id: I_ARMI_ND_ELEMENTS3
+            :tests: R_ARMI_ND_ELEMENTS
         """
         for ee in elements.byZ.values():
             if ee.z == 43 or ee.z == 61 or 84 <= ee.z <= 89 or ee.z >= 93:
@@ -104,6 +126,12 @@ def test_abundancesAddToOne(self):
             )
 
     def test_isHeavyMetal(self):
+        """Get elements by Z.
+
+        .. test:: Get elements by Z, to show if they are heavy metals.
+            :id: I_ARMI_ND_ELEMENTS4
+            :tests: R_ARMI_ND_ELEMENTS
+        """
         for ee in elements.byZ.values():
             if ee.z > 89:
                 self.assertTrue(ee.isHeavyMetal())

armi/nucDirectory/tests/test_nuclideBases.py

@@ -137,6 +137,12 @@ def test_NaturalNuclide_atomicWeightIsAverageOfNaturallyOccuringIsotopes(self):
             )
 
     def test_nucBases_labelAndNameCollsionsAreForSameNuclide(self):
+        """The name and labels for correct for nuclides.
+
+        .. test:: Validate the name, label, and DB name are accessible for nuclides.
+            :id: I_ARMI_ND_ISOTOPES0
+            :tests: R_ARMI_ND_ISOTOPES
+        """
         count = 0
         for nuc in nuclideBases.where(lambda nn: nn.name == nn.label):
             count += 1
@@ -185,6 +191,12 @@ def test_nucBases_imposeBurnChainTransmutationBulkStatistics(self):
             )  # ternary fission
 
     def test_nucBases_imposeBurn_nuSF(self):
+        """Test the nuclide data from file (specifically neutrons / sponaneous fission).
+
+        .. test:: Test that nuclide data was read from file instead of code.
+            :id: I_ARMI_ND_DATA0
+            :tests: R_ARMI_ND_DATA
+        """
         actual = {
             nn.name: nn.nuSF for nn in nuclideBases.where(lambda nn: nn.nuSF > 0.0)
         }
@@ -235,6 +247,12 @@ def test_nucBases_AllDatabaseNamesAreUnique(self):
         )
 
     def test_nucBases_Am242m(self):
+        """Test the correct am242g and am242m abbreviations are supported.
+
+        .. test:: Specifically test for Am242 and Am242g because it is a special case.
+            :id: I_ARMI_ND_ISOTOPES1
+            :tests: R_ARMI_ND_ISOTOPES
+        """
         am242m = nuclideBases.byName["AM242"]
         self.assertEqual(am242m, nuclideBases.byName["AM242M"])
         self.assertEqual("nAm242m", am242m.getDatabaseName())
@@ -263,6 +281,12 @@ def test_getDecay(self):
         self.assertIsNone(nb.getDecay("sf"))
 
     def test_getEndfMatNum(self):
+        """Test get nuclides by name.
+
+        .. test:: Test get nuclides by name.
+            :id: I_ARMI_ND_ISOTOPES2
+            :tests: R_ARMI_ND_ISOTOPES
+        """
         self.assertEqual(nuclideBases.byName["U235"].getEndfMatNum(), "9228")
         self.assertEqual(nuclideBases.byName["U238"].getEndfMatNum(), "9237")
         self.assertEqual(nuclideBases.byName["PU239"].getEndfMatNum(), "9437")
@@ -365,7 +389,12 @@ def test_curieDefinitionWithRa226(self):
         self.assertAlmostEqual(activity, 0.9885593, places=6)
 
     def test_loadMcc2Data(self):
-        """Tests consistency with the `mcc-nuclides.yaml` input and the nuclides in the data model."""
+        """Tests consistency with the `mcc-nuclides.yaml` input and the nuclides in the data model.
+
+        .. test:: Test that MCC v2 IDs can be queried by nuclides.
+            :id: I_ARMI_ND_ISOTOPES3
+            :tests: R_ARMI_ND_ISOTOPES
+        """
         with open(os.path.join(RES, "mcc-nuclides.yaml")) as f:
             yaml = YAML(typ="rt")
             data = yaml.load(f)
@@ -381,7 +410,16 @@ def test_loadMcc2Data(self):
         self.assertEqual(len(nuclideBases.byMcc2Id), len(expectedNuclides))
 
     def test_loadMcc3Data(self):
-        """Tests consistency with the `mcc-nuclides.yaml` input and the nuclides in the data model."""
+        """Tests consistency with the `mcc-nuclides.yaml` input and the nuclides in the data model.
+
+        .. test:: Test that MCC v3 IDs can be queried by nuclides.
+            :id: I_ARMI_ND_ISOTOPES4
+            :tests: R_ARMI_ND_ISOTOPES
+
+        .. test:: Test the MCC nuclide data that was read from file instead of code.
+            :id: I_ARMI_ND_DATA1
+            :tests: R_ARMI_ND_DATA
+        """
         with open(os.path.join(RES, "mcc-nuclides.yaml")) as f:
             yaml = YAML(typ="rt")
             data = yaml.load(f)
@@ -398,9 +436,14 @@ def test_loadMcc3Data(self):
         self.assertEqual(len(nuclideBases.byMcc3Id), len(expectedNuclides) - 1)
 
 
-class test_getAAAZZZSId(unittest.TestCase):
+class TestAAAZZZSId(unittest.TestCase):
     def test_AAAZZZSNameGenerator(self):
+        """Test that AAAZZS ID name generator.
 
+        .. test:: Query the AAAZZS IDs can be retrieved for nuclides.
+            :id: I_ARMI_ND_ISOTOPES5
+            :tests: R_ARMI_ND_ISOTOPES
+        """
         referenceNucNames = [
             ("C", "120060"),
             ("U235", "2350920"),