libinephany 1.0.1__tar.gz → 1.0.3__tar.gz

libinephany-1.0.3/CODE_VERSION.cfg

@@ -0,0 +1 @@
+1.0.3

{libinephany-1.0.1/libinephany.egg-info → libinephany-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: libinephany
-Version: 1.0.1
+Version: 1.0.3
 Summary: Inephany library containing code commonly used by multiple subpackages.
 Author-email: Inephany <info@inephany.com>
 License: Apache 2.0

{libinephany-1.0.1 → libinephany-1.0.3}/libinephany/observations/observers/base_observers.py

@@ -44,6 +44,7 @@ class Observer(ABC):
         observer_config: ObserverConfig,
         should_standardize: bool = True,
         include_statistics: list[str] | None = None,
+        include_hparams: list[str] | None = None,
         **kwargs,
     ) -> None:
         """
@@ -52,6 +53,8 @@ class Observer(ABC):
         :param should_standardize: Whether standardization should be applied to returned values.
         :param include_statistics: If the observation uses the TensorStatistic model to return observations, names of the
         fields in the model to include in returned observations.
+        :param include_hparams: If the observation uses the HyperparameterStates model to return observations, names of the
+        hyperparameters to include in returned observations.
         :param kwargs: Miscellaneous keyword arguments.
         """
 
@@ -64,10 +67,17 @@ class Observer(ABC):
         self.should_standardize = should_standardize and self.can_standardize
 
         self.include_statistics: list[str] | None = None
+        self.include_hparams = include_hparams
 
         if include_statistics is not None:
             self.include_statistics = TensorStatistics.filter_include_statistics(include_statistics=include_statistics)
 
+        if self.requires_include_statistics and not self.include_statistics:
+            raise ValueError(f"{self.__class__.__name__} must be provided with include_statistics.")
+
+        if self.requires_include_hparams and not self.include_hparams:
+            raise ValueError(f"{self.__class__.__name__} must be provided with include_hparams.")
+
     @final
     @property
     def in_training_mode(self) -> bool:
@@ -143,6 +153,22 @@ class Observer(ABC):
 
         return True
 
+    @property
+    def requires_include_statistics(self) -> bool:
+        """
+        :return: Whether the observation requires include_statistics to be provided.
+        """
+
+        return False
+
+    @property
+    def requires_include_hparams(self) -> bool:
+        """
+        :return: Whether the observation requires include_hparams to be provided.
+        """
+
+        return False
+
     @property
     @abstractmethod
     def standardizer_key_infix(self) -> str:

{libinephany-1.0.1 → libinephany-1.0.3}/libinephany/observations/observers/global_observers/base_classes.py

@@ -1,6 +1,6 @@
 # ======================================================================================================================
 #
-# BASE CLASSES
+# IMPORTS
 #
 # ======================================================================================================================
 
@@ -15,6 +15,12 @@ from libinephany.pydantic_models.schemas.observation_models import ObservationIn
 from libinephany.pydantic_models.schemas.tensor_statistics import TensorStatistics
 from libinephany.pydantic_models.states.hyperparameter_states import HyperparameterStates
 
+# ======================================================================================================================
+#
+# CLASSES
+#
+# ======================================================================================================================
+
 
 class LHOPTBaseObserver(GlobalObserver, ABC):
     """
@@ -33,13 +39,14 @@ class LHOPTBaseObserver(GlobalObserver, ABC):
         :param kwargs: Other observation keyword arguments.
         """
         super().__init__(**kwargs)
-        self.decay_factor = max(0.0, decay_factor)
-        self.time_window = max(1, time_window)
 
         # Store time series data for CDF calculation
         self._time_series: list[tuple[float, float]] = []  # (time, value) pairs
         self._current_time: float = 0.0
 
+        self.decay_factor = max(0.0, decay_factor)
+        self.time_window = max(1, time_window)
+
     @property
     def can_standardize(self) -> bool:
         """
@@ -48,6 +55,28 @@ class LHOPTBaseObserver(GlobalObserver, ABC):
         """
         return False
 
+    @staticmethod
+    def _compute_log_ratio(numerator: float, denominator: float) -> float:
+        """
+        Compute the log ratio.
+
+        :param numerator: Numerator value
+        :param denominator: Denominator value
+        :return: Log ratio value
+        """
+        # Calculate the ratio of numerator to denominator
+        invalid_denominator = math.isinf(denominator) or math.isnan(denominator)
+
+        if denominator <= LHOPT_CONSTANTS["ZERO_DIVISION_TOLERANCE"] or invalid_denominator:
+            return 0.0
+
+        ratio = numerator / denominator
+
+        if ratio <= 0:
+            return 0.0
+
+        return math.log(ratio)
+
     def _get_observation_format(self) -> StatisticStorageTypes:
         """
         :return: Format the observation returns data in. Must be one of the StatisticStorageTypes
@@ -68,18 +97,6 @@ class LHOPTBaseObserver(GlobalObserver, ABC):
         """Update the current time counter."""
         self._current_time += 1.0
 
-    def get_required_trackers(self) -> dict[str, dict[str, Any] | None]:
-        """
-        :return: Dictionary mapping statistic tracker class names to kwargs for the class or None if no kwargs are
-        needed.
-        """
-        return {}
-
-    def reset(self) -> None:
-        """Reset the observer by clearing the time series."""
-        self._time_series = []
-        self._current_time = 0.0
-
     @abstractmethod
     def _observe(
         self,
@@ -94,27 +111,13 @@ class LHOPTBaseObserver(GlobalObserver, ABC):
         :param tracked_statistics: Dictionary mapping statistic tracker class names to dictionaries mapping module
         :param action_taken: Action taken by the agent this class instance is assigned to.
         """
-        raise NotImplementedError
-
-    def _compute_log_ratio(self, numerator: float, denominator: float) -> float:
-        """
-        Compute the log ratio.
-
-        :param numerator: Numerator value
-        :param denominator: Denominator value
-        :return: Log ratio value
-        """
-        # Calculate the ratio of numerator to denominator
 
-        if denominator <= LHOPT_CONSTANTS["ZERO_DIVISION_TOLERANCE"]:
-            return 0.0
+        ...
 
-        ratio = numerator / denominator
-
-        if ratio <= 0:
-            return 0.0
-
-        return math.log(ratio)
+    def reset(self) -> None:
+        """Reset the observer by clearing the time series."""
+        self._time_series = []
+        self._current_time = 0.0
 
 
 class LHOPTCheckpointBaseObserver(GlobalObserver, ABC):
@@ -128,8 +131,10 @@ class LHOPTCheckpointBaseObserver(GlobalObserver, ABC):
         :param kwargs: Miscellaneous keyword arguments.
         """
         super().__init__(**kwargs)
-        self.checkpoint_interval = checkpoint_interval
+
         self._history: list[float] = []
+
+        self.checkpoint_interval = checkpoint_interval
         self.last_value: float | None = None
 
     @property
@@ -175,18 +180,6 @@ class LHOPTCheckpointBaseObserver(GlobalObserver, ABC):
         if self.last_value is None:
             self.last_value = value
 
-    def get_required_trackers(self) -> dict[str, dict[str, Any] | None]:
-        """
-        :return: Dictionary mapping statistic tracker class names to kwargs for the class or None if no kwargs are
-        needed.
-        """
-        return {}
-
-    def reset(self) -> None:
-        """Reset the observer by clearing history."""
-        self._history = []
-        self.last_value = None
-
     @abstractmethod
     def _observe(
         self,
@@ -201,24 +194,17 @@ class LHOPTCheckpointBaseObserver(GlobalObserver, ABC):
         :param tracked_statistics: Dictionary mapping statistic tracker class names to dictionaries mapping module
         :param action_taken: Action taken by the agent this class instance is assigned to.
         """
-        raise NotImplementedError
 
-    def _compute_log_ratio(self, numerator: float, denominator: float) -> float:
-        """
-        Compute the log ratio.
+        ...
 
-        :param numerator: Numerator value
-        :param denominator: Denominator value
-        :return: Log ratio value
+    def get_required_trackers(self) -> dict[str, dict[str, Any] | None]:
         """
-        # Calculate the ratio of numerator to denominator
-
-        if denominator <= LHOPT_CONSTANTS["ZERO_DIVISION_TOLERANCE"]:
-            return 0.0
-
-        ratio = numerator / denominator
-
-        if ratio <= 0:
-            return 0.0
+        :return: Dictionary mapping statistic tracker class names to kwargs for the class or None if no kwargs are
+        needed.
+        """
+        return {}
 
-        return math.log(ratio)
+    def reset(self) -> None:
+        """Reset the observer by clearing history."""
+        self._history = []
+        self.last_value = None

{libinephany-1.0.1 → libinephany-1.0.3}/libinephany/observations/observers/global_observers/constants.py

@@ -1,11 +1,17 @@
 # ======================================================================================================================
 #
-# CONSTANTS
+# IMPORTS
 #
 # ======================================================================================================================
 
 from typing import TypedDict
 
+# ======================================================================================================================
+#
+# CLASSES
+#
+# ======================================================================================================================
+
 
 class LHOPTConstants(TypedDict):
     IS_NAN: float
@@ -23,6 +29,13 @@ class LHOPTConstants(TypedDict):
     DEFAULT_ENV_STEP_SAMPLE_FREQUENCY: int
 
 
+# ======================================================================================================================
+#
+# CONSTANTS
+#
+# ======================================================================================================================
+
+
 # Create the constants instance
 LHOPT_CONSTANTS: LHOPTConstants = LHOPTConstants(
     IS_NAN=1.0,

{libinephany-1.0.1 → libinephany-1.0.3}/libinephany/observations/observers/global_observers/gradient_observers.py

@@ -1,6 +1,6 @@
 # ======================================================================================================================
 #
-# GRADIENT OBSERVERS
+# IMPORTS
 #
 # ======================================================================================================================
 
@@ -16,9 +16,23 @@ from libinephany.pydantic_models.schemas.observation_models import ObservationIn
 from libinephany.pydantic_models.schemas.tensor_statistics import TensorStatistics
 from libinephany.pydantic_models.states.hyperparameter_states import HyperparameterStates
 
+# ======================================================================================================================
+#
+# CLASSES
+#
+# ======================================================================================================================
+
 
 class GlobalFirstOrderGradients(GlobalObserver):
 
+    @property
+    def requires_include_statistics(self) -> bool:
+        """
+        :return: Whether the observation requires include_statistics to be provided.
+        """
+
+        return True
+
     def _get_observation_format(self) -> StatisticStorageTypes:
         """
         :return: Format the observation returns data in. Must be one of the enum attributes in the StatisticStorageTypes
@@ -74,6 +88,14 @@ class GlobalSecondOrderGradients(GlobalObserver):
 
         self.compute_hessian_diagonal = compute_hessian_diagonal
 
+    @property
+    def requires_include_statistics(self) -> bool:
+        """
+        :return: Whether the observation requires include_statistics to be provided.
+        """
+
+        return True
+
     def _get_observation_format(self) -> StatisticStorageTypes:
         """
         :return: Format the observation returns data in. Must be one of the enum attributes in the StatisticStorageTypes
@@ -136,21 +158,6 @@ class LHOPTGradientVarianceFraction(LHOPTBaseObserver):
         super().__init__(**kwargs)
         self.variance_threshold = variance_threshold
 
-    @property
-    def can_standardize(self) -> bool:
-        """
-        This observer has its own CDF calculation, no need to standardize.
-        :return: Whether the observation can be standardized.
-        """
-        return False
-
-    def _get_observation_format(self) -> StatisticStorageTypes:
-        """
-        :return: Format the observation returns data in. Must be one of the enum attributes in the StatisticStorageTypes
-        enumeration class.
-        """
-        return StatisticStorageTypes.VECTOR
-
     @property
     def vector_length(self) -> int:
         """
@@ -173,8 +180,6 @@ class LHOPTGradientVarianceFraction(LHOPTBaseObserver):
         :param action_taken: Action taken by the agent this class instance is assigned to.
         :return: Single float/int, list of floats/ints or TensorStatistics model to add to the observation vector.
         """
-        if statistic_trackers.GradientVarianceFraction.__name__ not in tracked_statistics:
-            return [0.0, 0.0]
 
         raw_value = list(tracked_statistics[statistic_trackers.GradientVarianceFraction.__name__].values())[0]  # type: ignore[list-item]
 
@@ -204,14 +209,6 @@ class LHOPTMomentumGradientRatio(LHOPTBaseObserver):
     It returns two-dimensional observations: [raw_value, cdf_feature] for momentum gradient ratio values.
     """
 
-    def _get_observation_format(self) -> StatisticStorageTypes:
-        """
-        :return: Format the observation returns data in. Must be one of the enum attributes in the StatisticStorageTypes
-        enumeration class.
-        """
-
-        return StatisticStorageTypes.VECTOR
-
     @property
     def vector_length(self) -> int:
         """
@@ -219,6 +216,14 @@ class LHOPTMomentumGradientRatio(LHOPTBaseObserver):
         """
         return 2  # [raw_value, cdf_feature]
 
+    @property
+    def requires_include_statistics(self) -> bool:
+        """
+        :return: Whether the observation requires include_statistics to be provided.
+        """
+
+        return True
+
     def _observe(
         self,
         observation_inputs: ObservationInputs,
@@ -266,29 +271,6 @@ class CosineSimilarityObserverOfGradientAndMomentum(LHOPTBaseObserver):
     It returns two-dimensional observations: [raw_value, cdf_feature] for cosine similarity of gradient and momentum values.
     """
 
-    def __init__(
-        self,
-        *,
-        include_statistics: list[str] | None = None,
-        **kwargs,
-    ) -> None:
-        """
-        :param include_statistics: List of statistics to include.
-        :param kwargs: Miscellaneous keyword arguments.
-        """
-
-        super().__init__(**kwargs)
-
-        self.include_statistics = include_statistics
-
-    def _get_observation_format(self) -> StatisticStorageTypes:
-        """
-        :return: Format the observation returns data in. Must be one of the enum attributes in the StatisticStorageTypes
-        enumeration class.
-        """
-
-        return StatisticStorageTypes.VECTOR
-
     @property
     def vector_length(self) -> int:
         """
@@ -296,6 +278,14 @@ class CosineSimilarityObserverOfGradientAndMomentum(LHOPTBaseObserver):
         """
         return 3  # [raw_value, cdf_feature, logit_of_cdf_feature]
 
+    @property
+    def requires_include_statistics(self) -> bool:
+        """
+        :return: Whether the observation requires include_statistics to be provided.
+        """
+
+        return True
+
     def _observe(
         self,
         observation_inputs: ObservationInputs,
@@ -351,29 +341,6 @@ class CosineSimilarityObserverOfGradientAndUpdate(LHOPTBaseObserver):
     It returns two-dimensional observations: [raw_value, cdf_feature] for cosine similarity of gradient and update values.
     """
 
-    def __init__(
-        self,
-        *,
-        include_statistics: list[str] | None = None,
-        **kwargs,
-    ) -> None:
-        """
-        :param include_statistics: List of statistics to include.
-        :param kwargs: Miscellaneous keyword arguments.
-        """
-
-        super().__init__(**kwargs)
-
-        self.include_statistics = include_statistics
-
-    def _get_observation_format(self) -> StatisticStorageTypes:
-        """
-        :return: Format the observation returns data in. Must be one of the enum attributes in the StatisticStorageTypes
-        enumeration class.
-        """
-
-        return StatisticStorageTypes.VECTOR
-
     @property
     def vector_length(self) -> int:
         """
@@ -381,6 +348,14 @@ class CosineSimilarityObserverOfGradientAndUpdate(LHOPTBaseObserver):
         """
         return 3  # [raw_value, cdf_feature, logit_of_cdf_feature]
 
+    @property
+    def requires_include_statistics(self) -> bool:
+        """
+        :return: Whether the observation requires include_statistics to be provided.
+        """
+
+        return True
+
     def _observe(
         self,
         observation_inputs: ObservationInputs,
@@ -436,28 +411,6 @@ class CosineSimilarityOfGradientAndParameter(LHOPTBaseObserver):
     It returns two-dimensional observations: [raw_value, cdf_feature] for cosine similarity of gradient and parameter values.
     """
 
-    def __init__(
-        self,
-        *,
-        include_statistics: list[str] | None = None,
-        **kwargs,
-    ) -> None:
-        """
-        :param include_statistics: List of statistics to include.
-        :param kwargs: Miscellaneous keyword arguments.
-        """
-        super().__init__(**kwargs)
-
-        self.include_statistics = include_statistics
-
-    def _get_observation_format(self) -> StatisticStorageTypes:
-        """
-        :return: Format the observation returns data in. Must be one of the enum attributes in the StatisticStorageTypes
-        enumeration class.
-        """
-
-        return StatisticStorageTypes.VECTOR
-
     @property
     def vector_length(self) -> int:
         """
@@ -465,6 +418,14 @@ class CosineSimilarityOfGradientAndParameter(LHOPTBaseObserver):
         """
         return 3  # [raw_value, cdf_feature, logit_of_cdf_feature]
 
+    @property
+    def requires_include_statistics(self) -> bool:
+        """
+        :return: Whether the observation requires include_statistics to be provided.
+        """
+
+        return True
+
     def _observe(
         self,
         observation_inputs: ObservationInputs,

{libinephany-1.0.1 → libinephany-1.0.3}/libinephany/observations/observers/global_observers/hyperparameter_observers.py

@@ -1,6 +1,6 @@
 # ======================================================================================================================
 #
-# HYPERPARAMETER OBSERVERS
+# IMPORTS
 #
 # ======================================================================================================================
 
@@ -12,25 +12,28 @@ from torch.optim import SGD, Adam, AdamW
 from libinephany.observations import observation_utils
 from libinephany.observations.observation_utils import StatisticStorageTypes
 from libinephany.observations.observers.base_observers import GlobalObserver
-from libinephany.observations.observers.global_observers.base_classes import LHOPT_CONSTANTS
+from libinephany.observations.observers.global_observers.constants import LHOPT_CONSTANTS
 from libinephany.pydantic_models.schemas.observation_models import ObservationInputs
 from libinephany.pydantic_models.schemas.tensor_statistics import TensorStatistics
 from libinephany.pydantic_models.states.hyperparameter_states import HyperparameterStates
 from libinephany.utils.enums import ModelFamilies
 
+# ======================================================================================================================
+#
+# CLASSES
+#
+# ======================================================================================================================
+
 
 class InitialHyperparameters(GlobalObserver):
 
-    def __init__(self, include_hparams: list[str] | None = None, pad_with: float = 0.0, **kwargs) -> None:
+    def __init__(self, pad_with: float = 0.0, **kwargs) -> None:
         """
-        :param include_hparams: Names of the hyperparameters to include in the initial values vector returned by
-        this observation.
         :param kwargs: Miscellaneous keyword arguments.
         """
 
         super().__init__(**kwargs)
 
-        self.include_hparams = include_hparams
         self.pad_with = pad_with
 
     @property
@@ -62,6 +65,14 @@ class InitialHyperparameters(GlobalObserver):
 
         return False
 
+    @property
+    def requires_include_hparams(self) -> bool:
+        """
+        :return: Whether the observation requires include_hparams to be provided.
+        """
+
+        return True
+
     def _get_observation_format(self) -> StatisticStorageTypes:
         """
         :return: Format the observation returns data in. Must be one of the enum attributes in the StatisticStorageTypes
@@ -298,7 +309,7 @@ class LHOPTHyperparameterRatio(GlobalObserver):
     providing insights into how much hyperparameters have changed from their starting values.
     """
 
-    def __init__(self, include_hparams: list[str] | None = None, pad_with: float = 0.0, **kwargs) -> None:
+    def __init__(self, pad_with: float = 0.0, **kwargs) -> None:
         """
         :param include_hparams: Names of the hyperparameters to include in the initial values vector returned by
         this observation.
@@ -307,7 +318,6 @@ class LHOPTHyperparameterRatio(GlobalObserver):
 
         super().__init__(**kwargs)
 
-        self.include_hparams = include_hparams
         self.pad_with = pad_with
 
     @property
@@ -339,6 +349,14 @@ class LHOPTHyperparameterRatio(GlobalObserver):
 
         return False
 
+    @property
+    def requires_include_hparams(self) -> bool:
+        """
+        :return: Whether the observation requires include_hparams to be provided.
+        """
+
+        return True
+
     def _get_observation_format(self) -> StatisticStorageTypes:
         """
         :return: Format the observation returns data in. Must be one of the enum attributes in the StatisticStorageTypes