From 8599ea96624308797b32dda57d09e649f426f103 Mon Sep 17 00:00:00 2001
From: Andreas Tsouchlos <an.tsouchlos@gmail.com>
Date: Tue, 22 Nov 2022 16:46:28 +0100
Subject: [PATCH] Added docstrings and TODOs

---
 sw/utility/simulation.py | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/sw/utility/simulation.py b/sw/utility/simulation.py
index 8d63a9d..503e22c 100644
--- a/sw/utility/simulation.py
+++ b/sw/utility/simulation.py
@@ -227,6 +227,7 @@ class Simulator:
 
 # TODO: Fix typing.Any or Simulator
 class SimulationDeSerializer:
+    """Class responsible for file management, de- and serialization of Simulator objects."""
     def __init__(self, save_dir: str, results_dir: str):
         self._save_dir = save_dir
         self._results_dir = results_dir
@@ -243,14 +244,32 @@ class SimulationDeSerializer:
     def _get_results_path(self, sim_name):
         return f"{self._results_dir}/{misc.slugify(sim_name)}.csv"
 
+    # TODO: Should this function also check for the metadata file?
+    #  Currently, if the state-savefile is present, but not the metadata,
+    #  this function will return true but loading the saved state will fail
     def unfinished_sim_present(self, sim_name: str):
+        """Check if the savefile of a previously paused simulation is present.
+
+        :param sim_name:
+        :return: True if a paused simulation with the given name is found
+        """
         return os.path.isfile(self._get_savefile_path(sim_name))
 
     def remove_unfinished_sim(self, sim_name):
+        """Remove the savefile of a previously paused simulation.
+
+        :param sim_name: Name of the simulation
+        """
         os.remove(self._get_savefile_path(sim_name))
         # os.remove(self._get_metadata_path(sim_name))
 
     def save_state(self, simulator: typing.Any, sim_name: str, metadata: typing.Dict) -> None:
+        """Save the state of a currently running simulation.
+
+        :param simulator: Simulator object
+        :param sim_name: Name of the simulation
+        :param metadata: Metadata to be saved besides the actual state
+        """
         # Save metadata
         with open(self._get_metadata_path(sim_name), 'w+', encoding='utf-8') as f:
             json.dump(metadata, f, ensure_ascii=False, indent=4)
@@ -260,6 +279,11 @@ class SimulationDeSerializer:
             pickle.dump(simulator, file)
 
     def read_state(self, sim_name: str) -> typing.Tuple[typing.Any, typing.Dict]:
+        """Read the saved state of a paused simulation.
+
+        :param sim_name: Name of the simulation
+        :return: Tuple of the form (simulator, metadata)
+        """
         metadata = None
         simulator = None
 
@@ -273,7 +297,14 @@ class SimulationDeSerializer:
 
         return simulator, metadata
 
+    # TODO: Is the simulator object actually necessary here?
     def save_results(self, simulator: typing.Any, sim_name: str, metadata: typing.Dict) -> None:
+        """Save simulation results to file.
+
+        :param simulator: Simulator object. Used to obtain the data
+        :param sim_name: Name of the simulation. Determines the filename
+        :param metadata: Metadata to be saved besides the actual simulation results
+        """
         # Save metadata
         with open(self._get_metadata_path(sim_name), 'w+', encoding='utf-8') as f:
             json.dump(metadata, f, ensure_ascii=False, indent=4)
@@ -289,6 +320,11 @@ class SimulationDeSerializer:
         df.to_csv(self._get_results_path(sim_name))
 
     def read_results(self, sim_name: str) -> typing.Tuple[pd.DataFrame, typing.Dict]:
+        """Read simulation results from file.
+
+        :param sim_name: Name of the simulation.
+        :return: Tuple of the form (data, metadata), where data is a pandas dataframe and metadata is a dict
+        """
         # Read metadata
         with open(self._get_metadata_path(sim_name), 'r', encoding='utf-8') as f:
             metadata = json.load(f)