Merge remote-tracking branch 'terrapower/main' into drewj-usnctech/le…

…ss-iter-components

* terrapower/main:
  Improving HexBlock getWettedPerimeter calculation (terrapower#1299)
  Sort components on representative block. (terrapower#1275)
  Unifying the Reactor sorting (terrapower#1280)
  Building helper tool for when Parameters need to be NumPy arrays (terrapower#1292)
  Apply decusping to individual assemblies. (terrapower#1282)
  Block collection burnup (terrapower#1265)
  Cleaning up TODOs (terrapower#1291)
  Docstring Improvements - linting (terrapower#1287)
  Adding the word Important, per user request (terrapower#1289)

.github/pull_request_template.md

@@ -1,6 +1,6 @@
 ## Description
 
-<!-- Mandatory: Please include a summary of the change and link to any related GitHub Issues.-->
+<!-- Mandatory: Include a summary of the change and link to any related GitHub Issues.-->
 
 ---
 
@@ -22,7 +22,6 @@
 
 <!-- Check the project-level cruft -->
 
-- [ ] The [release notes](https://terrapower.github.io/armi/release/index.html) (location `doc/release/0.X.rst`) are up-to-date with any bug fixes or new features.
+- [ ] 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.
 - [ ] The documentation is still up-to-date in the `doc` folder.
 - [ ] The dependencies are still up-to-date in `setup.py`.
-

armi/__init__.py

@@ -102,13 +102,13 @@
 
 
 def disableFutureConfigures():
-    """Exposed function to ensure armi.configure() isn't called more than once"""
+    """Exposed function to ensure armi.configure() isn't called more than once."""
     global _ignoreConfigures
     _ignoreConfigures = True
 
 
 def isStableReleaseVersion(version=None):
-    """Determine if the version should be considered a stable release"""
+    """Determine if the version should be considered a stable release."""
     version = version or __version__
     return "-" not in version
 

armi/apps.py

@@ -303,8 +303,9 @@ def _isPluginRegistered(self, pluginPath: str):
         return self._pm.has_plugin(pluginName)
 
     def __registerUserPluginsAbsPath(self, pluginPath):
-        """Helper method to register a single UserPlugin where
-        the given path is of the form: /path/to/why.py:MyPlugin
+        """Helper method to register a single UserPlugin via absolute path.
+
+        Here the given path is of the form: /path/to/why.py:MyPlugin
         """
         assert pluginPath.count(".py:") == 1, f"Invalid plugin path: {pluginPath}"
 
@@ -326,8 +327,9 @@ def __registerUserPluginsAbsPath(self, pluginPath):
             Flags.extend(newFlags)
 
     def __registerUserPluginsInternalImport(self, pluginPath):
-        """Helper method to register a single UserPlugin where
-        the given path is of the form: armi.thing.what.MyPlugin
+        """Helper method to register a single UserPlugin via internal import.
+
+        Here the given path is of the form: armi.thing.what.MyPlugin
         """
         names = pluginPath.strip().split(".")
         modPath = ".".join(names[:-1])

armi/bookkeeping/db/compareDB3.py

@@ -62,7 +62,7 @@
 
 
 class OutputWriter:
-    """Basically a tee to writeln to runLog and the output file"""
+    """Basically a tee to writeln to runLog and the output file."""
 
     def __init__(self, fname):
         self.fname = fname
@@ -138,7 +138,7 @@ def _getDefault(self) -> list:
         return [None] * (len(self._columns) - 1)
 
     def reportDiffs(self, stream: OutputWriter) -> None:
-        """Print out a well-formatted table of the non-zero diffs"""
+        """Print out a well-formatted table of the non-zero diffs."""
         # filter out empty rows
         diffsToPrint = {
             key: value

armi/bookkeeping/db/database3.py

@@ -67,22 +67,23 @@
     replaceNonesWithNonsense,
     replaceNonsenseWithNones,
 )
-from armi.reactor import parameters
-from armi.reactor.parameters import parameterCollections
-from armi.reactor.flags import Flags
-from armi.reactor.reactors import Core
+from armi.bookkeeping.db.typedefs import History, Histories
+from armi.nucDirectory import nuclideBases
+from armi.physics.neutronics.settings import CONF_LOADING_FILE
 from armi.reactor import assemblies
+from armi.reactor import grids
+from armi.reactor import parameters
+from armi.reactor import systemLayoutInput
 from armi.reactor.assemblies import Assembly
 from armi.reactor.blocks import Block
 from armi.reactor.components import Component
 from armi.reactor.composites import ArmiObject
-from armi.reactor import grids
-from armi.bookkeeping.db.typedefs import History, Histories
-from armi.reactor import systemLayoutInput
+from armi.reactor.flags import Flags
+from armi.reactor.parameters import parameterCollections
+from armi.reactor.reactors import Core
+from armi.settings.fwSettings.globalSettings import CONF_SORT_REACTOR
 from armi.utils import getNodesPerCycle
 from armi.utils.textProcessors import resolveMarkupInclusions
-from armi.nucDirectory import nuclideBases
-from armi.physics.neutronics.settings import CONF_LOADING_FILE
 
 # CONSTANTS
 _SERIALIZER_NAME = "serializerName"
@@ -377,7 +378,7 @@ def fileName(self, fName):
         self._fileName = fName
 
     def loadCS(self):
-        """Attempt to load settings from the database file
+        """Attempt to load settings from the database file.
 
         Notes
         -----
@@ -402,7 +403,7 @@ def loadCS(self):
         return cs
 
     def loadBlueprints(self):
-        """Attempt to load reactor blueprints from the database file
+        """Attempt to load reactor blueprints from the database file.
 
         Notes
         -----
@@ -528,7 +529,7 @@ def findReferences(name, obj):
                     destTs[key].attrs[attr] = "@{}".format(path)
 
     def __enter__(self):
-        """Context management support"""
+        """Context management support."""
         if self._openCount == 0:
             # open also increments _openCount
             self.open()
@@ -537,7 +538,7 @@ def __enter__(self):
         return self
 
     def __exit__(self, type, value, traceback):
-        """Typically we don't care why it broke but we want the DB to close"""
+        """Typically we don't care why it broke but we want the DB to close."""
         self._openCount -= 1
         # always close if there is a traceback.
         if self._openCount == 0 or traceback:
@@ -712,8 +713,8 @@ def load(
 
         Returns
         -------
-        root : ArmiObject
-            The top-level object stored in the database; usually a Reactor.
+        root : Reactor
+            The top-level object stored in the database; a Reactor.
         """
         runLog.info("Loading reactor state for time node ({}, {})".format(cycle, node))
 
@@ -756,7 +757,15 @@ def load(
         if updateGlobalAssemNum:
             updateGlobalAssemblyNum(root)
 
-        # usually a reactor object
+        # return a Reactor object
+        if cs[CONF_SORT_REACTOR]:
+            root.sort()
+        else:
+            runLog.warning(
+                "DeprecationWarning: This Reactor is not being sorted on DB load. "
+                f"Due to the setting {CONF_SORT_REACTOR}, this Reactor is unsorted. "
+                "But this feature is temporary and will be removed by 2024."
+            )
         return root
 
     @staticmethod
@@ -869,8 +878,7 @@ def _writeParams(self, h5group, comps):
                 if any(linkedDims):
                     attrs["linkedDims"] = numpy.array(linkedDims).astype("S")
             else:
-                # XXX: side effect is that after loading previously unset values will be
-                # the default
+                # NOTE: after loading, the previously unset values will be defaulted
                 temp = [c.p.get(paramDef.name, paramDef.default) for c in comps]
                 if paramDef.serializer is not None:
                     data, sAttrs = paramDef.serializer.pack(temp)
@@ -1527,7 +1535,7 @@ def packSpecialData(
     if len(nones) > 0:
         attrs["nones"] = True
 
-    # XXX: this whole if/then/elif/else can be optimized by looping once and then
+    # TODO: this whole if/then/elif/else can be optimized by looping once and then
     #      determining the correct action
     # A robust solution would need
     # to do this on a case-by-case basis, and re-do it any time we want to

armi/bookkeeping/db/databaseInterface.py

@@ -45,7 +45,7 @@
 
 
 def describeInterfaces(cs):
-    """Function for exposing interface(s) to other code"""
+    """Function for exposing interface(s) to other code."""
     return (DatabaseInterface, {"enabled": cs["db"]})
 
 
@@ -98,7 +98,7 @@ def database(self):
             )
 
     def interactBOL(self):
-        """Initialize the database if the main interface was not available. (Begining of Life)"""
+        """Initialize the database if the main interface was not available. (Begining of Life)."""
         if not self._db:
             self.initDB()
 
@@ -156,7 +156,7 @@ def interactEveryNode(self, cycle, node):
         self.writeDBEveryNode(cycle, node)
 
     def writeDBEveryNode(self, cycle, node):
-        """write the database at the end of the time node"""
+        """Write the database at the end of the time node."""
         # skip writing for last burn step since it will be written at interact EOC
         if node < self.o.burnSteps[cycle]:
             self.r.core.p.minutesSinceStart = (
@@ -167,7 +167,7 @@ def writeDBEveryNode(self, cycle, node):
                 self._db.syncToSharedFolder()
 
     def interactEOC(self, cycle=None):
-        """In case anything changed since last cycle (e.g. rxSwing), update DB. (End of Cycle)"""
+        """In case anything changed since last cycle (e.g. rxSwing), update DB. (End of Cycle)."""
         # We cannot presume whether we are at EOL based on cycle and cs["nCycles"],
         # since cs["nCycles"] is not a difinitive indicator of EOL; ultimately the
         # Operator has the final say.
@@ -178,15 +178,15 @@ def interactEOC(self, cycle=None):
             self._db.writeToDB(self.r)
 
     def interactEOL(self):
-        """DB's should be closed at run's end. (End of Life)"""
+        """DB's should be closed at run's end. (End of Life)."""
         # minutesSinceStarts should include as much of the ARMI run as possible so EOL
         # is necessary, too.
         self.r.core.p.minutesSinceStart = (time.time() - self.r.core.timeOfStart) / 60.0
         self._db.writeToDB(self.r)
         self._db.close(True)
 
     def interactError(self):
-        r"""Get shutdown state information even if the run encounters an error"""
+        r"""Get shutdown state information even if the run encounters an error."""
         try:
             self.r.core.p.minutesSinceStart = (
                 time.time() - self.r.core.timeOfStart

armi/bookkeeping/db/layout.py

@@ -356,8 +356,7 @@ def _initComps(self, caseTitle, bp):
             elif issubclass(Klass, Core):
                 comp = Klass(name)
             elif issubclass(Klass, Component):
-                # XXX: initialize all dimensions to 0, they will be loaded and assigned
-                # after load
+                # TODO: init all dimensions to 0, they will be loaded and assigned after load
                 kwargs = dict.fromkeys(Klass.DIMENSION_NAMES, 0)
                 kwargs["material"] = material
                 kwargs["name"] = name

armi/bookkeeping/db/permissions.py

@@ -14,7 +14,7 @@
 
 
 class Permissions:
-    """Mappings to HDF5 permissions flags"""
+    """Mappings to HDF5 permissions flags."""
 
     READ_ONLY_FME = "r"  # File Must Exist
     READ_WRITE_FME = "r+"  # File Must Exist

armi/bookkeeping/db/tests/__init__.py

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 """
-Database tests
+Database tests.
 """
 # Copyright 2009-2019 TerraPower, LLC
 #

armi/bookkeeping/db/tests/test_comparedb3.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Tests for the compareDB3 module"""
+"""Tests for the compareDB3 module."""
 # pylint: disable=missing-function-docstring,missing-class-docstring,abstract-method,protected-access
 import unittest
 
@@ -35,7 +35,7 @@
 
 
 class TestCompareDB3(unittest.TestCase):
-    """Tests for the compareDB3 module"""
+    """Tests for the compareDB3 module."""
 
     def setUp(self):
         self.td = TemporaryDirectoryChanger()
@@ -95,7 +95,7 @@ def test_diffResultsBasic(self):
         self.assertEqual(dr.nDiffs(), 10)
 
     def test_compareDatabaseDuplicate(self):
-        """end-to-end test of compareDatabases() on a photocopy database"""
+        """end-to-end test of compareDatabases() on a photocopy database."""
         # build two super-simple H5 files for testing
         o, r = test_reactors.loadTestReactor(
             TEST_ROOT, customSettings={"reloadDBName": "reloadingDB.h5"}
@@ -126,7 +126,7 @@ def test_compareDatabaseDuplicate(self):
         self.assertEqual(diffs.nDiffs(), 0)
 
     def test_compareDatabaseSim(self):
-        """end-to-end test of compareDatabases() on very simlar databases"""
+        """end-to-end test of compareDatabases() on very simlar databases."""
         # build two super-simple H5 files for testing
         o, r = test_reactors.loadTestReactor(
             TEST_ROOT, customSettings={"reloadDBName": "reloadingDB.h5"}

armi/bookkeeping/db/tests/test_database3.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-r""" Tests for the Database3 class"""
+r""" Tests for the Database3 class."""
 # pylint: disable=missing-function-docstring,missing-class-docstring,abstract-method,protected-access,no-member,disallowed-name,invalid-name
 import subprocess
 import unittest
@@ -25,13 +25,14 @@
 from armi.bookkeeping.db.databaseInterface import DatabaseInterface
 from armi.reactor import parameters
 from armi.reactor.tests.test_reactors import loadTestReactor, reduceTestReactorRings
+from armi.settings.fwSettings.globalSettings import CONF_SORT_REACTOR
 from armi.tests import TEST_ROOT
 from armi.utils import getPreviousTimeNode
 from armi.utils.directoryChangers import TemporaryDirectoryChanger
 
 
 class TestDatabase3(unittest.TestCase):
-    r"""Tests for the Database3 class"""
+    """Tests for the Database3 class."""
 
     def setUp(self):
         self.td = TemporaryDirectoryChanger()
@@ -332,6 +333,7 @@ def test_load(self):
         with self.assertRaises(KeyError):
             _r = self.db.load(0, 0)
 
+        # default load, should pass without error
         _r = self.db.load(0, 0, allowMissing=True)
 
         # show that we can use negative indices to load
@@ -350,6 +352,21 @@ def test_load(self):
         with self.assertRaises(RuntimeError):
             self.db.fileName = "whatever.h5"
 
+    def test_loadSortSetting(self):
+        self.makeShuffleHistory()
+
+        # default load, should pass without error
+        r0 = self.db.load(0, 0, allowMissing=True)
+
+        # test that the reactor loads differently, dependent on the setting
+        cs = self.db.loadCS()
+        cs = cs.modified(newSettings={CONF_SORT_REACTOR: False})
+        r1 = self.db.load(0, 0, cs=cs, allowMissing=True)
+
+        # the reactor / core should be the same size
+        self.assertEqual(len(r0), len(r1))
+        self.assertEqual(len(r0.core), len(r1.core))
+
     def test_load_updateGlobalAssemNum(self):
         from armi.reactor import assemblies
         from armi.reactor.assemblies import resetAssemNumCounter
@@ -426,7 +443,7 @@ def test_auxData(self):
 
     # TODO: This should be expanded.
     def test_replaceNones(self):
-        """Super basic test that we handle Nones correctly in database read/writes"""
+        """Super basic test that we handle Nones correctly in database read/writes."""
         data3 = numpy.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
         data1 = numpy.array([1, 2, 3, 4, 5, 6, 7, 8])
         data1iNones = numpy.array([1, 2, None, 5, 6])
@@ -542,7 +559,7 @@ def test_splitDatabase(self):
             )
 
     def test_grabLocalCommitHash(self):
-        """test of static method to grab a local commit hash with ARMI version"""
+        """Test of static method to grab a local commit hash with ARMI version."""
         # 1. test outside a Git repo
         localHash = database3.Database3.grabLocalCommitHash()
         self.assertEqual(localHash, "unknown")