ft-analyzer add docstrings and type hints

Author: pascal260303

tools/ft-analyzer/ftanalyzer/counter/continuous_counter.py

@@ -12,12 +12,16 @@ def __init__(
         has_negatives: bool = False,
         measure_start_time: np.uint64 = None,
         measure_end_time: np.uint64 = None,
-    ):
-        """Constructor
-
+    ) -> None:
+        """
+        Initialize a continuous-time counter.
         Args:
-            variable (str): _description_
-            start_time (np.uint64, optional): _description_. Defaults to np.uint64(0).
+            variable: Name of the observed variable.
+            sim: Simulation state object.
+            factor: Scaling factor for values.
+            has_negatives: If True, allow negative values for min.
+            measure_start_time: Start time for measurement window.
+            measure_end_time: End time for measurement window.
         """
         super().__init__(
             variable, "counter type: continuous-time counter", has_negatives
@@ -35,13 +39,23 @@ def __init__(
         self._sim = sim
 
     def get_mean(self) -> np.float64:
+        """
+        Returns the mean value over the measurement interval.
+        Returns:
+            Mean value as np.float64.
+        """
         interval = self.last_sample_time - self.first_sample_time
         if interval > 0:
             return np.float64(self.get_sum_power_one()) / np.float64(interval)
         else:
             return np.float64(0)
 
     def get_variance(self) -> np.float64:
+        """
+        Returns the variance over the measurement interval.
+        Returns:
+            Variance as np.float64.
+        """
         interval = self.last_sample_time - self.first_sample_time
         if interval > 0:
             mean = self.get_mean()
@@ -54,6 +68,11 @@ def get_variance(self) -> np.float64:
             return np.float64(0)
 
     def count(self, x: np.float64) -> None:
+        """
+        Count a new sample, updating statistics with time-weighted increments.
+        Args:
+            x: Value to count.
+        """
         if (
             self._sim.get_time() < self._measure_start_time
             or self._sim.get_time() > self._measure_end_time
@@ -78,6 +97,9 @@ def count(self, x: np.float64) -> None:
         self.last_sample_time = current_time
 
     def reset(self) -> None:
+        """
+        Reset all statistics and measurement window.
+        """
         super().reset()
         self.first_sample_time = self._sim.get_time()
         self.last_sample_time = self._sim.get_time()

tools/ft-analyzer/ftanalyzer/counter/counter.py

@@ -7,7 +7,9 @@
 
 
 class Counter(StatisticObject, ABC):
-    """Basic counter that counts: * sum power two * sum power one * minimum * maximum"""
+    """
+    Basic counter that tracks sum, sum of squares, minimum, maximum, and sample count for a variable.
+    """
 
     _sum_power_one: np.float64
     """Sum of values counted by this counter
@@ -32,12 +34,13 @@ def __init__(
         variable: str,
         type: str = "counter type: base counter",
         has_negatives: bool = False,
-    ):
-        """Constructor
-
+    ) -> None:
+        """
+        Initialize a counter for a given variable.
         Args:
-            variable (str): the observed variable
-            type (_type_, optional): the type of counter. Defaults to "counter type: base counter".
+            variable: Name of the observed variable.
+            type: Description of the counter type.
+            has_negatives: If True, allow negative values for min.
         """
         self.__counter_type = type
         self._observed_variable = variable
@@ -50,102 +53,102 @@ def __init__(
 
     @abstractmethod
     def get_mean(self) -> np.float64:
-        """Returns the mean of the observed variable
-
+        """
+        Returns the mean of the observed variable.
         Returns:
-            np.float64: the mean
+            Mean value as np.float64.
         """
         pass
 
     @abstractmethod
     def get_variance(self) -> np.float64:
-        """Returns the variance of the observed variable
-
+        """
+        Returns the variance of the observed variable.
         Returns:
-            np.float64: the variance
+            Variance as np.float64.
         """
         pass
 
     def get_std_deviation(self) -> np.float64:
-        """Returns the standard deviation of the observed variable
-
+        """
+        Returns the standard deviation of the observed variable.
         Returns:
-            np.float64: the standard deviation
+            Standard deviation as np.float64.
         """
         return math.sqrt(max(self.get_variance(), 0))
 
     def get_cvar(self) -> np.float64:
-        """Returns the co-variance of the observed variable
-
+        """
+        Returns the coefficient of variation of the observed variable.
         Returns:
-            np.float64: the co-variance
+            Coefficient of variation as np.float64.
         """
         if self.get_mean() == 0:
             return 0 if self.get_std_deviation() == 0 else np.finfo(np.float64).max
         else:
             return self.get_std_deviation() / self.get_mean()
 
     def get_min(self) -> np.float64:
-        """Returns the minimum of the observed variable
-
+        """
+        Returns the minimum value observed.
         Returns:
-            np.float64: the minimum
+            Minimum value as np.float64.
         """
         return self.__min
 
     def get_max(self) -> np.float64:
-        """Returns the maximum of the observed variable
-
+        """
+        Returns the maximum value observed.
         Returns:
-            np.float64: the maximum
+            Maximum value as np.float64.
         """
         return self.__max
 
     def get_num_samples(self) -> np.uint64:
-        """Returns the number of counted samples
-
+        """
+        Returns the number of counted samples.
         Returns:
-            np.uint64: the number of samples
+            Number of samples as np.uint64.
         """
         return self.__num_samples
 
     def get_sum_power_one(self) -> np.float64:
-        """Returns the sum of all counted samples
-
+        """
+        Returns the sum of all counted samples.
         Returns:
-            np.float64: the sum of all samples
+            Sum as np.float64.
         """
         return self._sum_power_one
 
-    def increase_sum_power_one(self, value: np.float64):
-        """Adds the given value to the sum of counted samples
-
+    def increase_sum_power_one(self, value: np.float64) -> None:
+        """
+        Add the given value to the sum of counted samples.
         Args:
-            value (np.float64): the value to add
+            value: Value to add.
         """
         self._sum_power_one += value
 
     def get_sum_power_two(self) -> np.float64:
-        """Returns the sum of all counted samples power two
-
+        """
+        Returns the sum of all counted samples squared.
         Returns:
-            np.float64: the sum of all samples power two
+            Sum of squares as np.float64.
         """
         return self._sum_power_two
 
-    def increase_sum_power_two(self, value: np.float64):
-        """Adds the given value to the sum of counted samples
-
+    def increase_sum_power_two(self, value: np.float64) -> None:
+        """
+        Add the given value to the sum of counted samples squared.
         Args:
-            value (np.float64): the value to add
+            value: Value to add.
         """
         self._sum_power_two += value
 
-    def count(self, x: np.float64):
-        """Counts a new sample (set min/max and increment sample counter)
-
+    def count(self, x: np.float64) -> None:
+        """
+        Count a new sample (set min/max and increment sample counter).
         Args:
-            x (np.float64): the value to count
+            x: Value to count.
         """
         self.__min = min(self.__min, x)
         if not self._has_negatives:
@@ -154,10 +157,10 @@ def count(self, x: np.float64):
         self.__num_samples += 1
 
     def report(self) -> str:
-        """Outputs the report of this counter to the command line
-
+        """
+        Output a string report of this counter.
         Returns:
-            str: output as string
+            Report as string.
         """
         out: str = ""
         if self._observed_variable:
@@ -176,19 +179,28 @@ def report(self) -> str:
 
         return out
 
-    def csv_report(self, output_dir: PathLike, is_ref: bool = False):
-        """Write Counter details to csv-file
-
+    def csv_report(self, output_dir: PathLike, is_ref: bool = False) -> None:
+        """
+        Write counter details to a CSV file.
         Args:
-            output_dir (PathLike): _description_
+            output_dir: Output directory for CSV file.
+            is_ref: If True, write to expected-counters folder.
         """
         content: str = f"{self._observed_variable};{self.__num_samples};{self.get_mean()};{self.get_variance()};{self.get_std_deviation()};{self.get_cvar()};{self.get_min()};{self.get_max()}\n"
         labels: str = "#counter ; numSamples ; MEAN; VAR; STD; CVAR; MIN; MAX\n"
         self._write_csv(output_dir, content, labels, is_ref)
 
     def _write_csv(
         self, output_dir: PathLike, content: str, labels: str, is_ref: bool = False
-    ):
+    ) -> None:
+        """
+        Helper to write CSV content to file.
+        Args:
+            output_dir: Output directory.
+            content: CSV content string.
+            labels: CSV header string.
+            is_ref: If True, write to expected-counters folder.
+        """
         try:
             dest = os.path.join(
                 output_dir, "expected-counters" if is_ref else "counters"
@@ -206,7 +218,10 @@ def _write_csv(
         except IOError as e:
             print(f"IOError while writing CSV: {e}")
 
-    def reset(self):
+    def reset(self) -> None:
+        """
+        Reset all statistics to initial state.
+        """
         self._sum_power_one = 0
         self._sum_power_two = 0
         self.__min = np.inf

tools/ft-analyzer/ftanalyzer/counter/discrete_counter.py

@@ -4,28 +4,25 @@
 
 class DiscreteCounter(Counter):
     """
-    Implements a discrete time counter, which updates statistics per discrete
-    observation.
+    Implements a discrete time counter, updating statistics per observation.
     """
 
     def __init__(
         self, variable: str, counter_type: str = "counter type: discrete-time counter"
-    ):
+    ) -> None:
         """
-        Constructor for DiscreteCounter.
-
+        Initialize a discrete time counter.
         Args:
-            variable (str): Name of the observed variable
-            counter_type (str, optional): Counter type label. Defaults to discrete-time counter.
+            variable: Name of the observed variable.
+            counter_type: Counter type label.
         """
         super().__init__(variable, counter_type)
 
     def get_mean(self) -> np.float64:
         """
-        Computes the mean of the observed variable over samples.
-
+        Compute the mean of the observed variable over samples.
         Returns:
-            np.float64: the mean value
+            Mean value as np.float64.
         """
         if self.get_num_samples() > 0:
             return np.float64(self.get_sum_power_one()) / np.float64(
@@ -36,10 +33,9 @@ def get_mean(self) -> np.float64:
 
     def get_variance(self) -> np.float64:
         """
-        Computes the sample variance of the observed variable.
-
+        Compute the sample variance of the observed variable.
         Returns:
-            np.float64: the variance
+            Variance as np.float64.
         """
         n = self.get_num_samples()
         if n > 1:
@@ -52,10 +48,9 @@ def get_variance(self) -> np.float64:
 
     def count(self, x: np.float64) -> None:
         """
-        Counts a new observation and updates first/second moments.
-
+        Count a new observation and update first/second moments.
         Args:
-            x (np.float64): the observation
+            x: The observation value.
         """
         super().count(x)
         self.increase_sum_power_one(x)