Adding impl tag descriptions to components (#1600)

armi/reactor/components/basicShapes.py

@@ -27,9 +27,14 @@
 class Circle(ShapedComponent):
     """A Circle.
 
-    .. impl:: Circle shaped component
+    .. impl:: Circle shaped Component
         :id: I_ARMI_COMP_SHAPES0
         :implements: R_ARMI_COMP_SHAPES
+
+        This class provides the implementation of a Circle Component. This includes
+        setting key parameters such as its material, temperature, and dimensions. It
+        also includes a method to retrieve the area of a Circle
+        Component via the ``getComponentArea`` method.
     """
 
     is3D = False
@@ -91,9 +96,15 @@ def isEncapsulatedBy(self, other):
 class Hexagon(ShapedComponent):
     """A Hexagon.
 
-    .. impl:: Hexagon shaped component
+    .. impl:: Hexagon shaped Component
         :id: I_ARMI_COMP_SHAPES1
         :implements: R_ARMI_COMP_SHAPES
+
+        This class provides the implementation of a hexagonal Component. This
+        includes setting key parameters such as its material, temperature, and
+        dimensions. It also includes methods for retrieving geometric
+        dimension information unique to hexagons such as the ``getPerimeter`` and
+        ``getPitchData`` methods.
     """
 
     is3D = False
@@ -176,9 +187,15 @@ def getPitchData(self):
 class Rectangle(ShapedComponent):
     """A Rectangle.
 
-    .. impl:: Rectangle shaped component
+    .. impl:: Rectangle shaped Component
         :id: I_ARMI_COMP_SHAPES2
         :implements: R_ARMI_COMP_SHAPES
+
+        This class provides the implementation for a rectangular Component. This
+        includes setting key parameters such as its material, temperature, and
+        dimensions. It also includes methods for computing geometric
+        information related to rectangles, such as the
+        ``getBoundingCircleOuterDiameter`` and ``getPitchData`` methods.
     """
 
     is3D = False
@@ -321,9 +338,14 @@ def getComponentArea(self, cold=False):
 class Square(Rectangle):
     """Square component that can be solid or hollow.
 
-    .. impl:: Square shaped component
+    .. impl:: Square shaped Component
         :id: I_ARMI_COMP_SHAPES3
         :implements: R_ARMI_COMP_SHAPES
+
+        This class provides the implementation for a square Component. This class
+        subclasses the ``Rectangle`` class because a square is a type of rectangle.
+        This includes setting key parameters such as its material, temperature, and
+        dimensions.
     """
 
     is3D = False
@@ -397,10 +419,15 @@ class Triangle(ShapedComponent):
     """
     Triangle with defined base and height.
 
-    .. impl:: Triangle shaped component
+    .. impl:: Triangle shaped Component
         :id: I_ARMI_COMP_SHAPES4
         :implements: R_ARMI_COMP_SHAPES
 
+        This class provides the implementation for defining a triangular Component. This
+        includes setting key parameters such as its material, temperature, and
+        dimensions. It also includes providing a method for retrieving the area of a
+        Triangle Component via the ``getComponentArea`` method.
+
     Notes
     -----
     The exact angles of the triangle are undefined. The exact side lenths and angles

armi/reactor/components/complexShapes.py

@@ -24,9 +24,14 @@
 class HoledHexagon(basicShapes.Hexagon):
     """Hexagon with n uniform circular holes hollowed out of it.
 
-    .. impl:: Holed hexagon shaped component
+    .. impl:: Holed hexagon shaped Component
         :id: I_ARMI_COMP_SHAPES5
         :implements: R_ARMI_COMP_SHAPES
+
+        This class provides an implementation for a holed hexagonal Component. This
+        includes setting key parameters such as its material, temperature, and
+        dimensions. It also provides the capability to retrieve the diameter of the
+        inner hole via the ``getCircleInnerDiameter`` method.
     """
 
     THERMAL_EXPANSION_DIMS = {"op", "holeOD"}
@@ -197,9 +202,15 @@ def getCircleInnerDiameter(self, Tc=None, cold=False):
 class HoledSquare(basicShapes.Square):
     """Square with one circular hole in it.
 
-    .. impl:: Holed square shaped component
+    .. impl:: Holed square shaped Component
         :id: I_ARMI_COMP_SHAPES6
         :implements: R_ARMI_COMP_SHAPES
+
+        This class provides an implementation for a holed square Component. This
+        includes setting key parameters such as its material, temperature, and
+        dimensions. It also includes methods to retrieve geometric
+        dimension information unique to holed squares via the ``getComponentArea`` and
+        ``getCircleInnerDiameter`` methods.
     """
 
     THERMAL_EXPANSION_DIMS = {"widthOuter", "holeOD"}
@@ -252,10 +263,16 @@ def getCircleInnerDiameter(self, Tc=None, cold=False):
 class Helix(ShapedComponent):
     """A spiral wire component used to model a pin wire-wrap.
 
-    .. impl:: Helix shaped component
+    .. impl:: Helix shaped Component
         :id: I_ARMI_COMP_SHAPES7
         :implements: R_ARMI_COMP_SHAPES
 
+        This class provides the implementation for a helical Component. This
+        includes setting key parameters such as its material, temperature, and
+        dimensions. It also includes the ``getComponentArea`` method to retrieve the
+        area of a helix. Helixes can be used for wire wrapping around fuel pins in fast
+        reactor designs.
+
     Notes
     -----
     http://mathworld.wolfram.com/Helix.html

armi/reactor/components/component.py

@@ -173,11 +173,21 @@ class Component(composites.Composite, metaclass=ComponentType):
         :id: I_ARMI_COMP_DEF
         :implements: R_ARMI_COMP_DEF
 
-    .. impl:: Order components by their outermost diameter (using the < operator).
+        The primitive object in an ARMI reactor is a Component. A Component is comprised
+        of a shape and composition. This class serves as a base class which all
+        Component types within ARMI are built upon. All primitive shapes (such as a
+        square, circle, holed hexagon, helix etc.) are derived from this base class.
+
+        Fundamental capabilities of this class include the ability to store parameters
+        and attributes which describe the physical state of each Component within the
+        ARMI data model.
+
+    .. impl:: Order Components by their outermost diameter (using the < operator).
         :id: I_ARMI_COMP_ORDER
         :implements: R_ARMI_COMP_ORDER
 
-        This is done via the __lt__() method, which is used to control sort() as the
+        Determining Component order by outermost diameters is implemented via
+        the __lt__() method, which is used to control sort() as the
         standard approach in Python. However, __lt__() does not show up in the API.
 
     Attributes
@@ -294,6 +304,13 @@ def resolveLinkedDims(self, components):
         .. impl:: The volume of some defined shapes depend on the solid components surrounding them.
             :id: I_ARMI_COMP_FLUID1
             :implements: R_ARMI_COMP_FLUID
+
+            Some Components are fluids and are thus defined by the shapes surrounding
+            them. This method cycles through each dimension defining the border of this
+            Component and converts the name of that Component to a link to the object
+            itself. This series of links is then used downstream to resolve
+            dimensional information.
+
         """
         for dimName in self.DIMENSION_NAMES:
             value = self.p[dimName]
@@ -400,9 +417,13 @@ def getProperties(self):
             :id: I_ARMI_COMP_MAT0
             :implements: R_ARMI_COMP_MAT
 
+            This method returns the material object that is assigned to the Component.
+
         .. impl:: Components have one-and-only-one material.
             :id: I_ARMI_COMP_1MAT
             :implements: R_ARMI_COMP_1MAT
+
+            This method returns the material object that is assigned to the Component.
         """
         return self.material
 
@@ -441,12 +462,14 @@ def setLumpedFissionProducts(self, lfpCollection):
 
     def getArea(self, cold=False):
         """
-        Get the area of a component in cm^2.
+        Get the area of a Component in cm^2.
 
-        .. impl:: Set a dimension of a component.
+        .. impl:: Get a dimension of a Component.
             :id: I_ARMI_COMP_VOL0
             :implements: R_ARMI_COMP_VOL
 
+            This method returns the area of a Component.
+
         See Also
         --------
         block.getVolumeFractions: component coolant is typically the "leftover" and is calculated and set here
@@ -466,12 +489,14 @@ def getArea(self, cold=False):
 
     def getVolume(self):
         """
-        Return the volume [cm^3] of the component.
+        Return the volume [cm^3] of the Component.
 
-        .. impl:: Set a dimension of a component.
+        .. impl:: Get a dimension of a Component.
             :id: I_ARMI_COMP_VOL1
             :implements: R_ARMI_COMP_VOL
 
+            This method returns the volume of a Component.
+
         Notes
         -----
         ``self.p.volume`` is not set until this method is called,
@@ -574,6 +599,10 @@ def containsSolidMaterial(self):
         .. impl:: Determine if a material is solid.
             :id: I_ARMI_COMP_SOLID
             :implements: R_ARMI_COMP_SOLID
+
+            For certain operations it is important to know if a Component is a solid or
+            fluid material. This method will return a boolean indicating if the material
+            is solid or not by checking if the material is an instance of the ``material.Fluid`` class.
         """
         return not isinstance(self.material, material.Fluid)
 
@@ -677,6 +706,10 @@ def setNumberDensity(self, nucName, val):
             :id: I_ARMI_COMP_NUCLIDE_FRACS0
             :implements: R_ARMI_COMP_NUCLIDE_FRACS
 
+            The method allows a user or plugin to set the number density of a Component.
+            It also indicates to other processes that may depend on a Component's
+            status about this change via the ``assigned`` attribute.
+
         Parameters
         ----------
         nucName : str
@@ -699,6 +732,10 @@ def setNumberDensities(self, numberDensities):
             :id: I_ARMI_COMP_NUCLIDE_FRACS1
             :implements: R_ARMI_COMP_NUCLIDE_FRACS
 
+            The method allows a user or plugin to set the number densities of a
+            Component. In contrast to the ``setNumberDensity`` method, it sets all
+            densities within a Component.
+
         Parameters
         ----------
         numberDensities : dict
@@ -802,10 +839,22 @@ def setDimension(self, key, val, retainLink=False, cold=True):
         """
         Set a single dimension on the component.
 
-        .. impl:: Set a component dimension, considering thermal expansion.
+        .. impl:: Set a Component dimension, considering thermal expansion.
             :id: I_ARMI_COMP_EXPANSION1
             :implements: R_ARMI_COMP_EXPANSION
 
+            Dimensions should be set considering the impact of thermal expansion. This
+            method allows for a user or plugin to set a dimension and indicate if the
+            dimension is for a cold configuration or not. If it is not for a cold
+            configuration, the thermal expansion factor is considered when setting the
+            dimension.
+
+            If the ``retainLink`` argument is ``True``, any Components linked to this
+            one will also have its dimensions changed consistently. After a dimension
+            is updated, the ``clearLinkedCache`` method is called which sets the
+            volume of this Component to ``None``. This ensures that when the volume is
+            next accessed it is recomputed using the updated dimensions.
+
         Parameters
         ----------
         key : str
@@ -843,6 +892,13 @@ def getDimension(self, key, Tc=None, cold=False):
             :id: I_ARMI_COMP_DIMS
             :implements: R_ARMI_COMP_DIMS
 
+            Due to thermal expansion, Component dimensions depend on their temperature.
+            This method retrieves a dimension from the Component at a particular
+            temperature, if provided. If the Component is a LinkedComponent then the
+            dimensions are resolved to ensure that any thermal expansion that has
+            occurred to the Components that the LinkedComponent depends on is reflected
+            in the returned dimension.
+
         Parameters
         ----------
         key : str
@@ -919,6 +975,15 @@ def getThermalExpansionFactor(self, Tc=None, T0=None):
             :id: I_ARMI_COMP_EXPANSION0
             :implements: R_ARMI_COMP_EXPANSION
 
+            This method enables the calculation of the thermal expansion factor
+            for a given material. If the material is solid, the difference
+            between T0 and Tc is used to calculate the thermal expansion
+            factor. If a solid material does not have a linear expansion factor
+            defined and the temperature difference is greater than
+            :py:attr:`armi.reactor.components.component.Component._TOLERANCE`, an
+            error is raised. Thermal expansion of fluids or custom materials is
+            neglected, currently.
+
         Parameters
         ----------
         Tc : float, optional

armi/reactor/tests/test_components.py

@@ -576,7 +576,22 @@ def test_getArea(self):
             self.assertAlmostEqual(cur, ref)
 
     def test_componentInteractionsLinkingByDimensions(self):
-        """Tests linking of components by dimensions."""
+        """Tests linking of Components by dimensions.
+
+        .. test:: Show the dimensions of a liquid Component can be defined to depend on the solid Components that bound it.
+            :id: T_ARMI_COMP_FLUID1
+            :tests: R_ARMI_COMP_FLUID
+
+        The component ``gap``, representing the fuel-clad gap filled with Void,
+        is defined with dimensions that depend on the fuel outer diameter and
+        clad inner diameter. The
+        :py:meth:`~armi.reactor.components.component.Component.resolveLinkedDims`
+        method links the gap dimensions appropriately when the Component is
+        constructed, and the test shows the area of the gap is calculated
+        correctly based on the thermally-expanded dimensions of the fuel and
+        clad Components.
+
+        """
         nPins = 217
         fuelDims = {"Tinput": 25.0, "Thot": 430.0, "od": 0.9, "id": 0.0, "mult": nPins}
         cladDims = {"Tinput": 25.0, "Thot": 430.0, "od": 1.1, "id": 1.0, "mult": nPins}