libinephany 0.16.1__py3-none-any.whl → 0.16.3__py3-none-any.whl

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
 
 # ======================================================================================================================
 #
@@ -280,3 +284,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/utils/constants.py

@@ -80,3 +80,4 @@ PREFIXES_TO_HPARAMS = {
     AGENT_PREFIX_SGD_MOMENTUM: SGD_MOMENTUM,
     AGENT_GRADIENT_ACCUMULATION: GRADIENT_ACCUMULATION,
 }
+HPARAMS_TO_PREFIXES = {hparam: prefix for prefix, hparam in PREFIXES_TO_HPARAMS.items()}

libinephany/utils/enums.py

@@ -78,6 +78,24 @@ class AgentTypes(EnumWithIndices):
     Tokens = TOKENS
     Samples = SAMPLES
 
+    @classmethod
+    def get_possible_active_agents(cls) -> list["AgentTypes"]:
+        """
+        :return: List of active agents.
+        """
+
+        return [
+            cls.LearningRateAgent,
+            cls.WeightDecayAgent,
+            cls.DropoutAgent,
+            cls.GradientClippingAgent,
+            cls.AdamBetaOneAgent,
+            cls.AdamBetaTwoAgent,
+            cls.AdamEpsAgent,
+            cls.SGDMomentumAgent,
+            cls.GradientAccumulationAgent,
+        ]
+
 
 class ModelFamilies(EnumWithIndices):
 

libinephany/utils/samplers.py

@@ -68,6 +68,13 @@ class Sampler:
 
         raise NotImplementedError
 
+    @classmethod
+    def get_subclasses(cls):
+        """Recursively gets subclasses of the Sampler class."""
+        for subclass in cls.__subclasses__():
+            yield from subclass.get_subclasses()
+            yield subclass
+
 
 class LogUniformSampler(Sampler):
 
@@ -228,6 +235,34 @@ class DiscreteValueSampler(Sampler):
         ).astype(self.sample_dtype)
 
 
+class DiscreteValueListSampler(DiscreteValueSampler):
+
+    def __init__(
+        self,
+        length: int,
+        discrete_values: list[float | int | str],
+        sample_dtype: type[np.generic | float | int | str] = np.float64,
+        **kwargs,
+    ) -> None:
+        """
+        :param length: Length of list to sample.
+        :param discrete_values: List of discrete values to sample from.
+        :param kwargs: Miscellaneous keyword arguments.
+        """
+
+        super().__init__(discrete_values=discrete_values, sample_dtype=sample_dtype)
+        self.list_length = length
+
+    def sample(self, number_of_samples: int = 1, **kwargs) -> list[np.ndarray | list[Any]]:
+        """
+        :param number_of_samples: Number of samples to make.
+        :param kwargs: Miscellaneous keyword arguments.
+        :return: Array of sampled values.
+        """
+
+        return [super().sample(number_of_samples=self.list_length) for _ in range(number_of_samples)]
+
+
 class RoundRobinDiscreteValueSampler(Sampler):
 
     def __init__(
@@ -287,7 +322,7 @@ def build_sampler(sampler_name: str, lower_bound: float | int, upper_bound: floa
     :return: Constructed sampler.
     """
 
-    possible_samplers = {sampler_type.__name__: sampler_type for sampler_type in Sampler.__subclasses__()}
+    possible_samplers = {sampler_type.__name__: sampler_type for sampler_type in Sampler.get_subclasses()}
 
     try:
         return possible_samplers[sampler_name](lower_bound=lower_bound, upper_bound=upper_bound, **kwargs)  # type: ignore

{libinephany-0.16.1.dist-info → libinephany-0.16.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: libinephany
-Version: 0.16.1
+Version: 0.16.3
 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.1.dist-info → libinephany-0.16.3.dist-info}/RECORD

@@ -2,7 +2,7 @@ libinephany/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 libinephany/aws/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 libinephany/aws/s3_functions.py,sha256=W8u85A6tDloo4FlJvydJbVHCUq_m9i8KDGdnKzy-Xpg,1745
 libinephany/observations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-libinephany/observations/observation_utils.py,sha256=z3WfEf7Dvj8sS0FmbPpjolPeFWX64SVUJF5Rydf3Whs,9949
+libinephany/observations/observation_utils.py,sha256=wsCxVIhtCmJpaTKq9AcYsJGc9WK5qO_RE4DK_fzBE8w,16703
 libinephany/observations/observer_pipeline.py,sha256=RvMH-TTDTu1Nk4S_KSHDkII1YuIRMSOXkPhn6g4B9ow,12815
 libinephany/observations/pipeline_coordinator.py,sha256=mw3c5jy_BWvNigUKNjIWMpReOjxFDblzOcWtsIkcls4,7907
 libinephany/observations/statistic_manager.py,sha256=LLg1zSxnJr2oQQepYla3qoUuRy10rsthr9jta4wEbnc,8956
@@ -32,16 +32,16 @@ libinephany/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU
 libinephany/utils/agent_utils.py,sha256=_2w1AY5Y4mQ5hes_Rq014VhZXOtIOn-W92mZgeixv3g,2658
 libinephany/utils/asyncio_worker.py,sha256=Ew23zKIbG1zwyCudcyiObMrw4G0f3p2QXzZfM4mePqI,2751
 libinephany/utils/backend_statuses.py,sha256=ZbpBPbz0qKmeqxyGGN_ePTrQ7Wrxh7KM6W26UDbPXtQ,644
-libinephany/utils/constants.py,sha256=piawYQa51vCxxAHCH3YoWOgUhTlgqgQxKMCenkoQTsc,2170
+libinephany/utils/constants.py,sha256=Qh8iz5o1R4UDVVCB69jOQPX2SLWRCncpb_2yTHpFSbY,2259
 libinephany/utils/directory_utils.py,sha256=408unVeE_5_Hm-ZYZuxc9sdvfuU0CgYELX7EzPlPieo,1217
 libinephany/utils/dropout_utils.py,sha256=X43yCW7Dh1cC5sNnivgS5j1fn871K_RCvxCBTT0YHKg,3392
-libinephany/utils/enums.py,sha256=kEECkJO2quKAyVAqzgOzOP-d4qIENE3z_RyymSvyIB8,2420
+libinephany/utils/enums.py,sha256=6_6k_1I2BwYTIfquUOsoaQT5fkhMXUWtwCxLoTYuFyU,2906
 libinephany/utils/error_severities.py,sha256=B9oidqOVaYOe0W6P6GwjpmuDsrkyTX30v1xdiUStCFk,1427
 libinephany/utils/exceptions.py,sha256=kgwLpHOgy3kciUz_I18xnYsWRtzdonfadUtwG2uDYk8,1823
 libinephany/utils/import_utils.py,sha256=WzC6V6UIa0nCiU2MekROwG82fWBh9RuVzichtby5EvM,1495
 libinephany/utils/optim_utils.py,sha256=-PLqsyuq4ZH3spBy_olNB3yuLwvhnLrCF0384elCmXc,8777
 libinephany/utils/random_seeds.py,sha256=eF-ErrMShu8mp9V_gXrB_iUxR-Lb-OtHypEEUQAGn2Y,1565
-libinephany/utils/samplers.py,sha256=uyVGAy5cm5bCyWMOuySJmzUc_vFuieO_3zydJciwdv4,12158
+libinephany/utils/samplers.py,sha256=7h_el2dLJi2J97f_zpvc4BrEzoM_EJgZk1-ZjRkOhZ8,13357
 libinephany/utils/standardizers.py,sha256=pG1K_XL4OR_NjVtT6Hjbln1dk1BtQdDuSK1PQTkA17Y,8014
 libinephany/utils/torch_distributed_utils.py,sha256=UPMfhdZZwyHX_r3h55AAK4PcB-zFtjK37Z5aawAKNmE,2968
 libinephany/utils/torch_utils.py,sha256=o5TsqrXe6Id04P6SqB_avGBRZutbu6IBB61llAHQ_PY,2696
@@ -50,8 +50,8 @@ libinephany/utils/typing.py,sha256=rGbaPO3MaUndsWiC_wHzReD_TOLYqb43i01pKN-j7Xs,6
 libinephany/web_apps/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 libinephany/web_apps/error_logger.py,sha256=gAQIaqerqP4ornXZwFF1cghjnd2mMZEt3aVrTuUCr34,16653
 libinephany/web_apps/web_app_utils.py,sha256=qiq_lasPipgN1RgRudPJc342kYci8O_4RqppxmIX8NY,4095
-libinephany-0.16.1.dist-info/licenses/LICENSE,sha256=pogfDoMBP07ehIOvWymuWIar8pg2YLUhqOHsJQU3wdc,9250
-libinephany-0.16.1.dist-info/METADATA,sha256=qqXRHyzLSH1dm1SlIbn2dthXuQ-WH00OsbTvM8RmwcE,8354
-libinephany-0.16.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-libinephany-0.16.1.dist-info/top_level.txt,sha256=bYAOXQdJgIoLkO2Ui0kxe7pSYegS_e38u0dMscd7COQ,12
-libinephany-0.16.1.dist-info/RECORD,,
+libinephany-0.16.3.dist-info/licenses/LICENSE,sha256=pogfDoMBP07ehIOvWymuWIar8pg2YLUhqOHsJQU3wdc,9250
+libinephany-0.16.3.dist-info/METADATA,sha256=qMiO9s8TRo6kshtkrv79aGT1BYQFjO55-9th2Wm7rdk,8390
+libinephany-0.16.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+libinephany-0.16.3.dist-info/top_level.txt,sha256=bYAOXQdJgIoLkO2Ui0kxe7pSYegS_e38u0dMscd7COQ,12
+libinephany-0.16.3.dist-info/RECORD,,