From 0a4bad779a5e2abad29653910db1885ea340418e Mon Sep 17 00:00:00 2001
From: John Stilley <1831479+john-science@users.noreply.github.com>
Date: Mon, 27 Nov 2023 07:58:15 -0800
Subject: [PATCH] Adding impl/test crumbs for the Database (#1493)

---
 armi/bookkeeping/db/__init__.py             |  4 ----
 armi/bookkeeping/db/database3.py            | 17 ++++++++++++++
 armi/bookkeeping/db/layout.py               |  6 +++++
 armi/bookkeeping/db/tests/test_database3.py | 25 +++++++++++++++++++++
 4 files changed, 48 insertions(+), 4 deletions(-)

diff --git a/armi/bookkeeping/db/__init__.py b/armi/bookkeeping/db/__init__.py
index 7edf2f9c7..336d4c85d 100644
--- a/armi/bookkeeping/db/__init__.py
+++ b/armi/bookkeeping/db/__init__.py
@@ -249,10 +249,6 @@ def _getH5File(db):
 
     All this being said, we are probably violating this already with genAuxiliaryData,
     but we have to start somewhere.
-
-    .. impl:: The ARMI output file has a language-agnostic format.
-        :id: I_ARMI_DB_H5
-        :implements: R_ARMI_DB_H5
     """
     if isinstance(db, Database3):
         return db.h5db
diff --git a/armi/bookkeeping/db/database3.py b/armi/bookkeeping/db/database3.py
index cba50dbba..c2a60d892 100644
--- a/armi/bookkeeping/db/database3.py
+++ b/armi/bookkeeping/db/database3.py
@@ -109,6 +109,10 @@ class Database3:
     handles the packing and unpacking of the structure of the objects, their
     relationships, and their non-parameter attributes.
 
+    .. impl:: The database files are H5, and thus language agnostic.
+        :id: I_ARMI_DB_H51
+        :implements: R_ARMI_DB_H5
+
     See Also
     --------
     `doc/user/outputs/database` for more details.
@@ -423,6 +427,7 @@ def loadBlueprints(self):
     def loadGeometry(self):
         """
         This is primarily just used for migrations.
+
         The "geometry files" were replaced by ``systems:`` and ``grids:`` sections of ``Blueprints``.
         """
         geom = systemLayoutInput.SystemLayoutInput()
@@ -437,6 +442,14 @@ def writeInputsToDB(self, cs, csString=None, geomString=None, bpString=None):
         implementation should be very stable, so we dont want it to be easy to change
         one Database implementation's behavior when trying to change another's.
 
+        .. impl:: The run settings are saved the settings file.
+            :id: I_ARMI_DB_CS
+            :implements: R_ARMI_DB_CS
+
+        .. impl:: The reactor blueprints are saved the settings file.
+            :id: I_ARMI_DB_BP
+            :implements: R_ARMI_DB_BP
+
         Notes
         -----
         This is hard-coded to read the entire file contents into memory and write that
@@ -659,6 +672,10 @@ def load(
         continue with new settings (or if blueprints are not on the database).
         Geometry is read from the database itself.
 
+        .. test:: Users can load a reactor from a DB.
+            :id: I_ARMI_DB_R_LOAD
+            :tests: R_ARMI_DB_R_LOAD
+
         Parameters
         ----------
         cycle : int
diff --git a/armi/bookkeeping/db/layout.py b/armi/bookkeeping/db/layout.py
index a49877a4e..347e28155 100644
--- a/armi/bookkeeping/db/layout.py
+++ b/armi/bookkeeping/db/layout.py
@@ -381,6 +381,12 @@ def _initComps(self, caseTitle, bp):
         return comps, groupedComps
 
     def writeToDB(self, h5group):
+        """Write a chunk of data to the database.
+
+        .. test:: Write data to the DB for a given time step.
+            :id: I_ARMI_DB_TIME
+            :tests: R_ARMI_DB_TIME
+        """
         if "layout/type" in h5group:
             # It looks like we have already written the layout to DB, skip for now
             return
diff --git a/armi/bookkeeping/db/tests/test_database3.py b/armi/bookkeeping/db/tests/test_database3.py
index a9676692b..7ca30ca3f 100644
--- a/armi/bookkeeping/db/tests/test_database3.py
+++ b/armi/bookkeeping/db/tests/test_database3.py
@@ -55,6 +55,12 @@ def tearDown(self):
         self.td.__exit__(None, None, None)
 
     def test_writeToDB(self):
+        """Test writing to the database.
+
+        .. test:: Write a single time step of data to the database.
+            :id: T_ARMI_DB_TIME
+            :tests: R_ARMI_DB_TIME
+        """
         self.r.p.cycle = 0
         self.r.p.timeNode = 0
         self.r.p.cycleLength = 0
@@ -67,6 +73,7 @@ def test_writeToDB(self):
         self.db.writeToDB(self.r)
         self.assertEqual(sorted(self.db.h5db.keys()), ["c00n00", "inputs"])
 
+        # check the keys for a single time step
         keys = [
             "Circle",
             "Core",
@@ -345,6 +352,12 @@ def test_computeParents(self):
         )
 
     def test_load(self):
+        """Load a reactor at different time steps, from the database.
+
+        .. test:: Load the reactor from the database.
+            :id: T_ARMI_DB_R_LOAD
+            :tests: R_ARMI_DB_R_LOAD
+        """
         self.makeShuffleHistory()
         with self.assertRaises(KeyError):
             _r = self.db.load(0, 0)
@@ -601,14 +614,26 @@ def test_fileName(self):
         self.assertEqual(str(self.db.fileName), "thing.h5")
 
     def test_readInputsFromDB(self):
+        """Test that we can read inputs from the database.
+
+        .. test:: Save and retrieve settings from the database.
+            :id: T_ARMI_DB_CS
+            :tests: R_ARMI_DB_CS
+
+        .. test:: Save and retrieve blueprints from the database.
+            :id: T_ARMI_DB_BP
+            :tests: R_ARMI_DB_BP
+        """
         inputs = self.db.readInputsFromDB()
         self.assertEqual(len(inputs), 3)
 
+        # settings
         self.assertGreater(len(inputs[0]), 100)
         self.assertIn("settings:", inputs[0])
 
         self.assertEqual(len(inputs[1]), 0)
 
+        # blueprints
         self.assertGreater(len(inputs[2]), 100)
         self.assertIn("custom isotopics:", inputs[2])
         self.assertIn("blocks:", inputs[2])