libinephany 0.16.2__tar.gz → 0.16.4__tar.gz

libinephany-0.16.4/CODE_VERSION.cfg

@@ -0,0 +1 @@
+0.16.4

{libinephany-0.16.2/libinephany.egg-info → libinephany-0.16.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: libinephany
-Version: 0.16.2
+Version: 0.16.4
 Summary: Inephany library containing code commonly used by multiple subpackages.
 Author-email: Inephany <info@inephany.com>
 License: Apache 2.0
@@ -18,6 +18,7 @@ Requires-Dist: pydantic<3.0.0,>=2.5.0
 Requires-Dist: loguru<0.8.0,>=0.7.0
 Requires-Dist: requests<3.0.0,>=2.28.0
 Requires-Dist: numpy<2.0.0,>=1.24.0
+Requires-Dist: scipy<2.0.0,>=1.10.0
 Requires-Dist: slack-sdk<4.0.0,>=3.20.0
 Requires-Dist: boto3<2.0.0,>=1.26.0
 Requires-Dist: fastapi<0.116.0,>=0.100.0

{libinephany-0.16.2 → libinephany-0.16.4}/libinephany/observations/observation_utils.py

@@ -13,6 +13,7 @@ import numpy as np
 import pandas as pd
 import torch
 import torch.optim as optim
+from scipy.stats import norm
 
 from libinephany.pydantic_models.schemas.tensor_statistics import TensorStatistics
 from libinephany.utils import optim_utils
@@ -24,6 +25,9 @@ from libinephany.utils import optim_utils
 # ======================================================================================================================
 
 EXP_AVERAGE = "exp_avg"
+MIN_DECAY_FACTOR = 1e-10
+
+MIN_TOTAL_WEIGHT = 1e-15  # Minimum total weight threshold for numerical stability
 
 # ======================================================================================================================
 #
@@ -60,20 +64,8 @@ def get_exponential_weighted_average(values: list[int | float]) -> float:
     :param values: List of values to average via EWA.
     :return: EWA of the given values.
     """
-
-    # Check for NaN and infinite values in input
-    valid_values = [float(val) for val in values if not math.isnan(float(val)) and not math.isinf(float(val))]
-
-    if not valid_values:
-        raise ValueError("Cannot compute exponential weighted average on empty list")
-
-    if len(valid_values) == 1:
-        return valid_values[0]
-
-    exp_weighted_average = pd.Series(valid_values).ewm(alpha=0.1).mean().iloc[-1]
+    exp_weighted_average = pd.Series(values).ewm(alpha=0.1).mean().iloc[-1]
     assert isinstance(exp_weighted_average, float)
-    assert not math.isnan(exp_weighted_average)
-    assert not math.isinf(exp_weighted_average)
     return exp_weighted_average
 
 
@@ -280,3 +272,165 @@ def concatenate_lists(lists: list[list[Any]]) -> list[Any]:
     """
 
     return list(chain(*lists))
+
+
+def compute_cdf_weighted_mean_and_std(
+    time_series: list[tuple[float, float]], decay_factor: float
+) -> tuple[float, float]:
+    """
+    Compute the CDF-weighted standard deviation using the same exponential decay weights
+    as the mean calculation, with numerical integration.
+
+    :param time_series: List of (time, value) pairs
+    :param decay_factor: Decay factor b in the exponential weight formula b in [1.25, 2.5, 5, 10, 20]
+    :return: Tuple of (weighted mean, weighted standard deviation)
+    """
+
+    if len(time_series) == 0:
+        return 0.0, 0.0
+
+    if len(time_series) == 1:
+        return time_series[0][1], 0.0
+
+    sorted_series = sorted(time_series, key=lambda x: x[0])
+
+    # Handle the special case when decay_factor = 1.0
+    if abs(decay_factor - 1.0) < MIN_DECAY_FACTOR:
+        # When decay_factor = 1.0, w(t) = 1 for all t
+        # So the result is just the arithmetic mean
+        values = [v for _, v in sorted_series]
+        mean = float(np.mean(values))
+        std = float(np.std(values))
+        return mean, std
+
+    log_decay_factor = math.log(decay_factor)
+
+    total_weight = 0.0  # ∫ w(t) dt - total weight across all time intervals
+    total_weighted_value = 0.0  # ∫ w(t) y(t) dt - total weighted value
+    total_weighted_squared = 0.0  # ∫ w(t) y(t)² dt - total weighted squared value
+
+    for time_series_index in range(len(sorted_series) - 1):
+        start_time_point = sorted_series[time_series_index][0]
+        end_time_point = sorted_series[time_series_index + 1][0]
+        start_value = sorted_series[time_series_index][1]
+        end_value = sorted_series[time_series_index + 1][1]
+
+        time_interval = end_time_point - start_time_point
+        assert time_interval > 0, "Time interval must be positive"
+
+        interval_value = _weighted_interval_expectation(
+            start_time_point=start_time_point,
+            start_value=start_value,
+            end_time_point=end_time_point,
+            end_value=end_value,
+            log_decay_factor=log_decay_factor,
+        )
+        interval_squared_value = _weighted_interval_expectation(
+            start_time_point=start_time_point,
+            start_value=start_value**2,
+            end_time_point=end_time_point,
+            end_value=end_value**2,
+            log_decay_factor=log_decay_factor,
+        )
+
+        total_weighted_value += interval_value
+        total_weighted_squared += interval_squared_value
+
+    total_weight = (1 / log_decay_factor) * (
+        math.exp(log_decay_factor * sorted_series[-1][0]) - math.exp(log_decay_factor * sorted_series[0][0])
+    )
+    # Check if total weight is too small (numerical stability)
+    if total_weight < MIN_TOTAL_WEIGHT:
+        values = [v for _, v in sorted_series]
+        mean = float(np.mean(values))
+        std = float(np.std(values))
+        return mean, std
+
+    # Calculate weighted mean: μ = ∫ w(t) y(t) dt / ∫ w(t) dt
+    # This gives us the expected value under the weight distribution
+    weighted_mean = float(total_weighted_value / total_weight)
+
+    # Calculate weighted variance: Var = ∫ w(t) y(t)² dt / ∫ w(t) dt - μ²
+    # This follows from the definition: Var(X) = E[X²] - (E[X])²
+    # where E[X] = ∫ w(t) y(t) dt / ∫ w(t) dt and E[X²] = ∫ w(t) y(t)² dt / ∫ w(t) dt
+    weighted_variance = float(total_weighted_squared / total_weight - weighted_mean**2)
+
+    # Calculate weighted standard deviation: σ = √Var
+    # This is the square root of the variance, representing the spread of values
+    weighted_std = float(math.sqrt(max(0, weighted_variance)))
+
+    return weighted_mean, weighted_std
+
+
+def _weighted_interval_expectation(
+    start_time_point: float,
+    start_value: float,
+    end_time_point: float,
+    end_value: float,
+    log_decay_factor: float,
+) -> float:
+    """
+    Computes the weighted interval expectation from Appendix E of the LHOPT paper.
+
+    :param start_time_point: the start time value of the interval.
+    :param start_value: the value at start_time_point.
+    :param end_time_point: the end time value of the interval.
+    :param end_value: the value at end_time_point.
+    :param log_decay_factor: the logarithm of the decay factor used to weight the expectation.
+    :return: the exponentially-weighted expectation of the linear interpolation between the start and end points.
+    """
+
+    interval_gradient = (end_value - start_value) / (end_time_point - start_time_point)
+    start_exp_time = math.exp(log_decay_factor * start_time_point)
+    end_exp_time = math.exp(log_decay_factor * end_time_point)
+    return (1 / log_decay_factor) * (end_value * end_exp_time - start_value * start_exp_time) - (
+        1 / log_decay_factor**2
+    ) * interval_gradient * (end_exp_time - start_exp_time)
+
+
+def compute_cdf_feature(
+    current_value: float,
+    time_series: list[tuple[float, float]],
+    decay_factor: float,
+    current_time: float,
+    time_window: int,
+) -> float:
+    """
+
+    This function computes a CDF feature that represents the cumulative probability
+    of the current value given the historical distribution, weighted by time decay.
+    Uses scipy.stats.norm.cdf with loc (mean) and scale (std) computed from CDF utilities.
+
+    The mean and std formula from the OpenAI paper:
+    https://arxiv.org/pdf/2305.18290.pdf
+
+
+    :param current_value: Current value to compute CDF feature for
+    :param time_series: List of (time, value) pairs for CDF calculation. time_series will be updated in-place each time this function is called.
+    :param decay_factor: Decay factor for CDF calculation (0 < factor < 1)
+    :param current_time: Current time step
+    :param time_window: Maximum number of time steps to keep in time series
+    :return: CDF feature value (cumulative probability from normal distribution)
+    """
+    # Add current observation to time series
+    time_series.append((current_time, current_value))
+
+    # Keep only the last time_window observations
+    if len(time_series) > time_window:
+        time_series[:] = time_series[-time_window:]
+
+    # If we don't have enough data, return 0.0
+    if len(time_series) < 2:
+        return 0.0
+
+    # Compute CDF-weighted mean (loc) and standard deviation (scale)
+    cdf_mean, cdf_std = compute_cdf_weighted_mean_and_std(time_series, decay_factor)
+
+    # Compute CDF feature using scipy.stats.norm.cdf
+    if cdf_std > 0:
+        # Use norm.cdf with loc=cdf_mean and scale=cdf_std
+        cdf_feature = norm.cdf(current_value, loc=cdf_mean, scale=cdf_std)
+        return cdf_feature
+    else:
+        # If the standard deviation is 0, return 0.0
+        return 0.0

libinephany-0.16.4/libinephany/observations/observers/global_observers/__init__.py

@@ -0,0 +1,58 @@
+# ======================================================================================================================
+#
+# GLOBAL OBSERVERS PACKAGE
+#
+# This package contains all global observer classes used for collecting observations
+# across the entire training process, not specific to individual agents.
+#
+# ======================================================================================================================
+
+
+from .gradient_observers import GlobalFirstOrderGradients, GlobalSecondOrderGradients
+from .hyperparameter_observers import InitialHyperparameters, ModelFamilyOneHot, OptimizerTypeOneHot
+from .loss_observers import (
+    LHOPTLossRatio,
+    LHOPTTrainingLoss,
+    LHOPTValidationLoss,
+    LossRatio,
+    PercentileOfLossAtEachCheckpoint,
+    TrainingLoss,
+    TrainingScore,
+    ValidationLoss,
+    ValidationScore,
+)
+from .model_observers import (
+    GlobalActivations,
+    GlobalLAMBTrustRatio,
+    GlobalParameters,
+    GlobalParameterUpdates,
+    NumberOfLayers,
+    NumberOfParameters,
+)
+from .progress_observers import EpochsCompleted, ProgressAtEachCheckpoint, TrainingProgress
+
+__all__ = [
+    InitialHyperparameters.__name__,
+    OptimizerTypeOneHot.__name__,
+    ModelFamilyOneHot.__name__,
+    TrainingLoss.__name__,
+    ValidationLoss.__name__,
+    LossRatio.__name__,
+    TrainingScore.__name__,
+    ValidationScore.__name__,
+    GlobalFirstOrderGradients.__name__,
+    GlobalSecondOrderGradients.__name__,
+    GlobalActivations.__name__,
+    GlobalParameterUpdates.__name__,
+    GlobalParameters.__name__,
+    GlobalLAMBTrustRatio.__name__,
+    NumberOfParameters.__name__,
+    NumberOfLayers.__name__,
+    TrainingProgress.__name__,
+    EpochsCompleted.__name__,
+    ProgressAtEachCheckpoint.__name__,
+    LHOPTTrainingLoss.__name__,
+    LHOPTValidationLoss.__name__,
+    LHOPTLossRatio.__name__,
+    PercentileOfLossAtEachCheckpoint.__name__,
+]

libinephany-0.16.4/libinephany/observations/observers/global_observers/base_classes.py

@@ -0,0 +1,183 @@
+# ======================================================================================================================
+#
+# BASE CLASSES
+#
+# ======================================================================================================================
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from libinephany.observations.observation_utils import StatisticStorageTypes, compute_cdf_feature
+from libinephany.observations.observers.base_observers import GlobalObserver
+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
+
+
+class LHOPTOuterStepBaseObserver(GlobalObserver, ABC):
+    """
+    Base class for LHOPT outer step observers to eliminate duplicate code.
+    """
+
+    def __init__(
+        self,
+        decay_factor: float = LHOPT_CONSTANTS["DEFAULT_DECAY_FACTOR"],
+        time_window: int = LHOPT_CONSTANTS["DEFAULT_TIME_WINDOW"],
+        **kwargs,
+    ) -> None:
+        """
+        :param decay_factor: Decay factor for CDF calculation in [1, 2.5, 5, 10, 20]
+        :param time_window: Number of time steps to consider for CDF calculation
+        :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
+
+    @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 StatisticStorageTypes
+        enumeration class.
+        """
+        return StatisticStorageTypes.VECTOR
+
+    def _compute_cdf_feature(self, value: float) -> float:
+        """
+        Compute CDF feature for the given value.
+        training loss will be added to the time series after this call.
+        :param value: The value to compute CDF feature for
+        :return: CDF feature value
+        """
+        return compute_cdf_feature(value, self._time_series, self.decay_factor, self._current_time, self.time_window)
+
+    def _update_time(self) -> None:
+        """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,
+        observation_inputs: ObservationInputs,
+        hyperparameter_states: HyperparameterStates,
+        tracked_statistics: dict[str, dict[str, float | TensorStatistics]],
+        action_taken: float | int | None,
+    ) -> float | int | list[int | float] | TensorStatistics:
+        """
+        :param observation_inputs: Observation input metrics not calculated with statistic trackers.
+        :param hyperparameter_states: HyperparameterStates that manages the hyperparameters.
+        :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
+
+
+class LHOPTCheckpointBaseObserver(GlobalObserver, ABC):
+    """
+    Base class for checkpoint-based observers to eliminate duplicate code.
+    """
+
+    def __init__(self, checkpoint_interval: int = LHOPT_CONSTANTS["DEFAULT_CHECKPOINT_INTERVAL"], **kwargs) -> None:
+        """
+        :param checkpoint_interval: How often to create checkpoints (in outer model steps).
+        :param kwargs: Miscellaneous keyword arguments.
+        """
+        super().__init__(**kwargs)
+        self.checkpoint_interval = checkpoint_interval
+        self._history: list[float] = []
+        self.last_value: float | None = None
+
+    @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.
+        """
+        return StatisticStorageTypes.FLOAT
+
+    def _update_history(self, value: float) -> None:
+        """
+        Update the history with a new value and maintain sliding window.
+
+        :param value: The new value to add to history
+        """
+        self._history.append(value)
+
+        # Keep only the last checkpoint_interval values for sliding window
+        if len(self._history) > self.checkpoint_interval:
+            self._history = self._history[-self.checkpoint_interval :]
+
+    def _should_create_checkpoint(self) -> bool:
+        """
+        Check if we should create a checkpoint.
+
+        :return: True if checkpoint should be created, False otherwise
+        """
+        return len(self._history) >= self.checkpoint_interval
+
+    def _cold_start(self, value: float) -> None:
+        """
+        Handle cold start by setting the last value if not already set.
+
+        :param value: The value to set as last value if cold start
+        """
+        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,
+        observation_inputs: ObservationInputs,
+        hyperparameter_states: HyperparameterStates,
+        tracked_statistics: dict[str, dict[str, float | TensorStatistics]],
+        action_taken: float | int | None,
+    ) -> float | int | list[int | float] | TensorStatistics:
+        """
+        :param observation_inputs: Observation input metrics not calculated with statistic trackers.
+        :param hyperparameter_states: HyperparameterStates that manages the hyperparameters.
+        :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

libinephany-0.16.4/libinephany/observations/observers/global_observers/constants.py

@@ -0,0 +1,33 @@
+# ======================================================================================================================
+#
+# CONSTANTS
+#
+# ======================================================================================================================
+
+from typing import TypedDict
+
+
+class LHOPTConstants(TypedDict):
+    IS_NAN: float
+    NOT_NAN: float
+    IS_INF: float
+    NOT_INF: float
+    TANH_BOUND: float
+    DEFAULT_DECAY_FACTOR: float
+    DEFAULT_TIME_WINDOW: int
+    DEFAULT_CHECKPOINT_INTERVAL: int
+    DEFAULT_PERCENTILE: float
+
+
+# Create the constants instance
+LHOPT_CONSTANTS: LHOPTConstants = LHOPTConstants(
+    IS_NAN=1.0,
+    NOT_NAN=0.0,
+    IS_INF=1.0,
+    NOT_INF=0.0,
+    TANH_BOUND=10.0,
+    DEFAULT_DECAY_FACTOR=1.25,
+    DEFAULT_TIME_WINDOW=32,
+    DEFAULT_CHECKPOINT_INTERVAL=100,
+    DEFAULT_PERCENTILE=0.6,
+)

libinephany-0.16.4/libinephany/observations/observers/global_observers/gradient_observers.py

@@ -0,0 +1,112 @@
+# ======================================================================================================================
+#
+# GRADIENT OBSERVERS
+#
+# ======================================================================================================================
+
+from typing import Any
+
+from libinephany.observations import observation_utils, statistic_trackers
+from libinephany.observations.observation_utils import StatisticStorageTypes
+from libinephany.observations.observers.base_observers import GlobalObserver
+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
+
+
+class GlobalFirstOrderGradients(GlobalObserver):
+
+    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.TENSOR_STATISTICS
+
+    def _observe(
+        self,
+        observation_inputs: ObservationInputs,
+        hyperparameter_states: HyperparameterStates,
+        tracked_statistics: dict[str, dict[str, float | TensorStatistics]],
+        action_taken: float | int | None,
+    ) -> float | int | list[int | float] | TensorStatistics:
+        """
+        :param observation_inputs: Observation input metrics not calculated with statistic trackers.
+        :param hyperparameter_states: HyperparameterStates that manages the hyperparameters.
+        :param tracked_statistics: Dictionary mapping statistic tracker class names to dictionaries mapping module
+        names to floats or TensorStatistic models.
+        :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.
+        """
+
+        statistics = tracked_statistics[statistic_trackers.FirstOrderGradients.__name__]
+
+        return observation_utils.average_tensor_statistics(tensor_statistics=list(statistics.values()))  # type: ignore
+
+    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 {statistic_trackers.FirstOrderGradients.__name__: dict(skip_statistics=self.skip_statistics)}
+
+
+class GlobalSecondOrderGradients(GlobalObserver):
+
+    def __init__(
+        self,
+        *,
+        compute_hessian_diagonal: bool = False,
+        **kwargs,
+    ) -> None:
+        """
+        :param compute_hessian_diagonal: Whether to compute the Hessian diagonal to determine second order gradients
+        or use the squared first order gradients as approximations in the same way Adam does.
+        :param kwargs: Miscellaneous keyword arguments.
+        """
+
+        super().__init__(**kwargs)
+
+        self.compute_hessian_diagonal = compute_hessian_diagonal
+
+    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.TENSOR_STATISTICS
+
+    def _observe(
+        self,
+        observation_inputs: ObservationInputs,
+        hyperparameter_states: HyperparameterStates,
+        tracked_statistics: dict[str, dict[str, float | TensorStatistics]],
+        action_taken: float | int | None,
+    ) -> float | int | list[int | float] | TensorStatistics:
+        """
+        :param observation_inputs: Observation input metrics not calculated with statistic trackers.
+        :param hyperparameter_states: HyperparameterStates that manages the hyperparameters.
+        :param tracked_statistics: Dictionary mapping statistic tracker class names to dictionaries mapping module
+        names to floats or TensorStatistic models.
+        :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.
+        """
+
+        statistics = tracked_statistics[statistic_trackers.SecondOrderGradients.__name__]
+
+        return observation_utils.average_tensor_statistics(tensor_statistics=list(statistics.values()))  # type: ignore
+
+    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 {
+            statistic_trackers.SecondOrderGradients.__name__: dict(
+                skip_statistics=self.skip_statistics, compute_hessian_diagonal=self.compute_hessian_diagonal
+            )
+        }