Merge 4d46724 into 75ced0b

armi/physics/fuelCycle/fuelHandlerInterface.py

@@ -36,6 +36,23 @@ class FuelHandlerInterface(interfaces.Interface):
         :id: I_ARMI_SHUFFLE
         :implements: R_ARMI_SHUFFLE
 
+        This interface allows for a user to define custom shuffle logic that
+        modifies to the core model. Being based on the :py:class:`~armi.interfaces.Interface`
+        class, it has direct access to the current core model.
+
+        User logic is able to be executed from within the
+        :py:meth:`~armi.physics.fuelCycle.fuelHandlerInterface.FuelHandlerInterface.manageFuel` method,
+        which will use the :py:meth:`~armi.physics.fuelCycle.fuelHandlerFactory.fuelHandlerFactory`
+        to search for a Python file specified by the case setting ``shuffleLogic``.
+        If it exists, the fuel handler with name specified by the user via the ``fuelHandlerName``
+        case setting will be imported, and any actions in its ``outage`` method
+        will be executed at the :py:meth:`~armi.physics.fuelCycle.fuelHandlerInterface.FuelHandlerInterface.interactBOC`
+        hook.
+
+        If no class with the name specified by the ``fuelHandlerName`` setting is found
+        in the file with path ``shuffleLogic``, an error is returned.
+
+        See the user manual for how the custom shuffle logic file should be constructed.
     """
 
     name = "fuelHandler"

armi/physics/fuelCycle/fuelHandlers.py

@@ -727,22 +727,38 @@ def swapAssemblies(self, a1, a2):
             :id: I_ARMI_SHUFFLE_MOVE
             :implements: R_ARMI_SHUFFLE_MOVE
 
-        .. impl:: User-specified blocks can be left in place and not moved.
+            For the two assemblies that are passed in, call to their :py:meth:`~armi.reactor.assemblies.Assembly.moveTo`
+            methods to transfer their underlying ``spatialLocator`` attributes to
+            each other. This will also update the ``childrenByLocator`` list on the
+            core as well as the assembly parameters ``numMoves`` and ``daysSinceLastMove``.
+
+        .. impl:: User-specified blocks can be left in place during within-core swaps.
             :id: I_ARMI_SHUFFLE_STATIONARY0
             :implements: R_ARMI_SHUFFLE_STATIONARY
 
+            Before assemblies are moved,
+            the ``_transferStationaryBlocks`` class method is called to
+            check if there are any block types specified by the user as stationary
+            via the ``stationaryBlockFlags`` case setting. Using these flags, blocks
+            are gathered from each assembly which should remain stationary and
+            checked to make sure that both assemblies have the same number
+            and same height of stationary blocks. If not, return an error.
+
+            If all checks pass, the :py:meth:`~armi.reactor.assemblies.Assembly.remove`
+            and :py:meth:`~armi.reactor.assemblies.Assembly.insert``
+            methods are used to swap the stationary blocks between the two assemblies.
+
+            Once this process is complete, the actual assembly movement can take
+            place. Through this process, the stationary blocks remain in the same
+            core location.
+
         Parameters
         ----------
         a1 : :py:class:`Assembly <armi.reactor.assemblies.Assembly>`
             The first assembly
         a2 : :py:class:`Assembly <armi.reactor.assemblies.Assembly>`
             The second assembly
 
-        Notes
-        -----
-        The implementation for ``R_ARMI_SHUFFLE_STATIONARY`` occurs within
-        :py:meth:`<armi.physics.fuelCyle.fuelHandlers.FuelHandler._transferStationaryBlocks`.
-
         See Also
         --------
         dischargeSwap : swap assemblies where one is outside the core and the other is inside
@@ -831,14 +847,26 @@ def dischargeSwap(self, incoming, outgoing):
         outgoing : :py:class:`Assembly <armi.reactor.assemblies.Assembly>`
             The assembly getting discharged out the core.
 
-        .. impl:: User-specified blocks can be left in place and not moved.
+        .. impl:: User-specified blocks can be left in place for the discharge swap.
             :id: I_ARMI_SHUFFLE_STATIONARY1
             :implements: R_ARMI_SHUFFLE_STATIONARY
 
-        Notes
-        -----
-        The implementation for ``R_ARMI_SHUFFLE_STATIONARY`` occurs within
-        :py:meth:`<armi.physics.fuelCyle.fuelHandlers.FuelHandler._transferStationaryBlocks`.
+            Before assemblies are moved,
+            the ``_transferStationaryBlocks`` class method is called to
+            check if there are any block types specified by the user as stationary
+            via the ``stationaryBlockFlags`` case setting. Using these flags, blocks
+            are gathered from each assembly which should remain stationary and
+            checked to make sure that both assemblies have the same number
+            and same height of stationary blocks. If not, return an error.
+
+            If all checks pass, the :py:meth:`~armi.reactor.assemblies.Assembly.remove`
+            and :py:meth:`~armi.reactor.assemblies.Assembly.insert``
+            methods are used to swap the stationary blocks between the two assemblies.
+
+            Once this process is complete, the actual assembly movement can take
+            place. Through this process, the stationary blocks from the outgoing
+            assembly remain in the original core position, while the stationary
+            blocks from the incoming assembly are discharged with the outgoing assembly.
 
         See Also
         --------