ai-nk-cce 0.1.0__tar.gz → 0.1.2__tar.gz

{ai_nk_cce-0.1.0 → ai_nk_cce-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: ai-nk-cce
-Version: 0.1.0
+Version: 0.1.2
 Summary: This repository is used to train AI agents to predict good strategies in a social learning game based on a NK landscape.
 Author: Luis Mienhardt
 Author-email: mienhardt@mpib-berlin.mpg.de

{ai_nk_cce-0.1.0 → ai_nk_cce-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "ai-nk-cce"
-version = "0.1.0"
+version = "0.1.2"
 description = "This repository is used to train AI agents to predict good strategies in a social learning game based on a NK landscape."
 authors = [
 "Luis Mienhardt <mienhardt@mpib-berlin.mpg.de>",

{ai_nk_cce-0.1.0 → ai_nk_cce-0.1.2}/src/nk_model/biased_prediction_agent.py

@@ -22,6 +22,8 @@ class BiasedPredictionAgent:
         landscape: NKLandscape,
         bias_seed: int | None = None,
         bias_power: float = 1.0,
+        adjust_mu_to_feasible: bool = True,
+        adjust_sigma2_to_feasible: bool = True,
     ):
         """
         Initialize the biased prediction agent.
@@ -32,9 +34,12 @@ class BiasedPredictionAgent:
             bias_power: Power applied to bias landscape G. Higher values
                 make the bias more pronounced for regions with higher G(x)
         """
-        self.landscape = landscape
+        self.landscape = self._normalize_landscape(landscape)
+        
         self.bias_seed = bias_seed
         self.bias_power = bias_power
+        self.adjust_mu_to_feasible = adjust_mu_to_feasible
+        self.adjust_sigma2_to_feasible = adjust_sigma2_to_feasible
 
         # Generate bias landscape G (N'=N, K'=0)
         self.bias_landscape = self._create_bias()
@@ -43,12 +48,59 @@ class BiasedPredictionAgent:
         self.biased_landscape = self._create_biased_landscape()
 
         # Cache for distributions: key=(x_tuple, radius, mu, sigma2),
-        # value=List of (coordinates, probability) tuples
+        # value=(item_distribution, actual_mu, actual_sigma2)
         self._distribution_cache: Dict[
             Tuple[Tuple[int, ...], int, float, float],
-            List[Tuple[np.ndarray, float]],
+            Tuple[List[Tuple[np.ndarray, float]], float, float],
         ] = {}
 
+    def _normalize_landscape(self, landscape: NKLandscape) -> NKLandscape:
+        """
+        Normalize landscape payoffs to [0, 1] range.
+
+        Args:
+            landscape: NKLandscape to normalize
+
+        Returns:
+            New NKLandscape with normalized payoffs
+        """
+        # Extract payoffs
+        payoffs = np.array([item.payoff for item in landscape.items])
+        min_payoff = np.min(payoffs)
+        max_payoff = np.max(payoffs)
+
+        # Normalize to [0, 1]
+        if max_payoff > min_payoff:
+            normalized_payoffs = (payoffs - min_payoff) / (
+                max_payoff - min_payoff
+            )
+        else:
+            normalized_payoffs = np.zeros_like(payoffs)
+
+        # Create new landscape with normalized payoffs
+        normalized_items = [
+            Item(
+                coordinates=item.coordinates.copy(),
+                payoff=normalized_payoffs[i],
+            )
+            for i, item in enumerate(landscape.items)
+        ]
+
+        # Create a new NKLandscape object
+        normalized_landscape = NKLandscape.__new__(NKLandscape)
+        normalized_landscape.params = landscape.params
+        normalized_landscape.N = landscape.N
+        normalized_landscape.K = landscape.K
+        normalized_landscape.M = landscape.M
+        normalized_landscape.items = normalized_items
+        normalized_landscape._payoff_lookup = {
+            tuple(item.coordinates): item.payoff
+            for item in normalized_items
+        }
+        normalized_landscape.uuid = f"{landscape.uuid}_normalized"
+
+        return normalized_landscape
+
     def _create_bias(self) -> NKLandscape:
         """
         Create bias landscape G with N'=N, K'=0.
@@ -133,7 +185,8 @@ class BiasedPredictionAgent:
         radius: int,
         delta_mu: float,
         sigma2: float,
-    ) -> Item:
+        max_mu_factor: float = 0.5,
+    ) -> Tuple[Item, Tuple[float, float]]:
         """
         Generate a biased suggestion from distribution p_x.
 
@@ -142,17 +195,31 @@ class BiasedPredictionAgent:
             radius: Locality parameter r (Hamming distance radius)
             delta_mu: Expected improvement delta over F'(x)
             sigma2: Variance of improvement suggestions
+            max_mu_factor: Maximum fraction of distance to extremes that mu
+                can move from current_fitness (default: 0.5)
 
         Returns:
-            Suggested Item from original (unbiased) landscape
+            Tuple of (suggested_item, (actual_delta_mu, actual_sigma2)) where:
+            - suggested_item: Suggested Item from original (unbiased) landscape
+            - actual_delta_mu: Actual delta_mu used after feasibility
+                adjustments (may differ from input if adjusted)
+            - actual_sigma2: Actual sigma2 used after feasibility adjustments
+                (may differ from input if adjusted)
         """
         # Compute absolute mu from delta_mu
         current_fitness = self.landscape.get_payoff(x)
         mu = current_fitness + delta_mu
 
         # Get or compute distribution over all landscape items
-        item_distribution = self.generate_prediction_distribution(
-            x, radius, mu, sigma2
+        item_distribution, actual_mu, actual_sigma2 = (
+            self.generate_prediction_distribution(
+                x=x,
+                radius=radius,
+                mu=mu,
+                sigma2=sigma2,
+                current_fitness=current_fitness,
+                max_mu_factor=max_mu_factor,
+            )
         )
 
         # Extract coordinates and probabilities
@@ -163,10 +230,12 @@ class BiasedPredictionAgent:
         sampled_idx = np.random.choice(len(coordinates), p=probabilities)
         sampled_coords = coordinates[sampled_idx]
 
-        # Find and return the corresponding Item from original landscape
+        # Find the corresponding Item from original landscape
         for item in self.landscape.items:
             if np.array_equal(item.coordinates, sampled_coords):
-                return item
+                # Convert actual_mu back to delta_mu
+                actual_delta_mu = actual_mu - current_fitness
+                return (item, (actual_delta_mu, actual_sigma2))
 
         raise ValueError(
             f"Item with coordinates {sampled_coords} not found"
@@ -178,7 +247,9 @@ class BiasedPredictionAgent:
         radius: int,
         mu: float,
         sigma2: float,
-    ) -> List[Tuple[np.ndarray, float]]:
+        current_fitness: float,
+        max_mu_factor: float = 0.5,
+    ) -> Tuple[List[Tuple[np.ndarray, float]], float, float]:
         """
         Generate prediction distribution p_x using maximum entropy.
 
@@ -190,31 +261,48 @@ class BiasedPredictionAgent:
             radius: Locality parameter r (Hamming distance radius)
             mu: Target mean fitness F'(y)
             sigma2: Target variance of fitness F'(y)
+            current_fitness: Current fitness value F'(x)
+            max_mu_factor: Maximum fraction of distance to extremes that mu
+                can move from current_fitness (default: 0.5)
 
         Returns:
-            List of (coordinates, probability) tuples for all items
+            Tuple of (item_distribution, actual_mu, actual_sigma2) where:
+            - item_distribution: List of (coordinates, probability) tuples
+                for all items
+            - actual_mu: Actual mu value used after feasibility adjustments
+            - actual_sigma2: Actual sigma2 value used after feasibility
+                adjustments
         """
         # Check cache
         x_tuple = tuple(x)
         cache_key = (x_tuple, radius, mu, sigma2)
         if cache_key in self._distribution_cache:
-            return self._distribution_cache[cache_key]
+            cached_dist, cached_mu, cached_sigma2 = (
+                self._distribution_cache[cache_key]
+            )
+            return cached_dist, cached_mu, cached_sigma2
 
         # Get ball items from original landscape
         ball_items = self.closed_ball(x, radius)
         ball_item_coordinates = [item.coordinates.copy() for item in ball_items]
 
-        # Check feasibility
-        self.feasible_mean_and_variance(ball_items, mu, sigma2)
+        # Check feasibility and get adjusted values
+        actual_mu, actual_sigma2 = self.feasible_mean_and_variance(
+            ball_items=ball_items,
+            mu=mu,
+            sigma2=sigma2,
+            current_fitness=current_fitness,
+            max_mu_factor=max_mu_factor,
+        )
 
         # Initialize distribution with zeros for all items
         item_distribution = [
             (item.coordinates.copy(), 0.0) for item in self.landscape.items
         ]
 
-        # Get probabilities for ball items
+        # Get probabilities for ball items using adjusted values
         ball_distribution = self.solve_constraint_minimization(
-            mu, sigma2, ball_item_coordinates
+            actual_mu, actual_sigma2, ball_item_coordinates
         )
 
         # Create lookup for ball items
@@ -231,30 +319,41 @@ class BiasedPredictionAgent:
             for coords, _ in item_distribution
         ]
 
-        # Cache result
-        self._distribution_cache[cache_key] = item_distribution
+        # Cache result with actual values
+        result = (item_distribution, actual_mu, actual_sigma2)
+        self._distribution_cache[cache_key] = result
 
-        return item_distribution
+        return result
 
     def feasible_mean_and_variance(
         self,
         ball_items: list[Item],
         mu: float,
         sigma2: float,
+        current_fitness: float,
+        max_mu_factor: float = 0.5,
     ):
         """
         Get feasible min and max fitness values and validate mu, sigma2.
 
+        When adjust_mu_to_feasible is True, mu is capped dynamically based on
+        max_mu_factor. The boundaries allow mu to move at most max_mu_factor
+        fraction of the distance from current_fitness toward each extreme.
+
         Args:
             ball_items: List of items in B_r(x) from original landscape
             mu: Target mean fitness F'(y)
             sigma2: Target variance of fitness F'(y)
+            current_fitness: Current fitness value F'(x)
+            max_mu_factor: Maximum fraction of distance to extremes that mu
+                can move from current_fitness (default: 0.5)
 
         Returns:
-            Tuple of (min_fitness, max_fitness) in B_r(x)
+            Tuple of (mu, sigma2) with adjusted values
 
         Raises:
-            ValueError: If mu or sigma2 are not feasible
+            ValueError: If mu or sigma2 are not feasible and adjustment
+                is disabled
         """
         fitnesses = [
             self.biased_landscape.get_payoff(item.coordinates)
@@ -263,8 +362,28 @@ class BiasedPredictionAgent:
         min_fitness = float(np.min(fitnesses))
         max_fitness = float(np.max(fitnesses))
 
-        # Check mean feasibility
-        if not (min_fitness <= mu <= max_fitness):
+        # Apply dynamic mu capping based on max_mu_factor
+        if self.adjust_mu_to_feasible:
+            # Calculate distances from current_fitness to extremes
+            dist_to_min = current_fitness - min_fitness
+            dist_to_max = max_fitness - current_fitness
+
+            # Calculate dynamic boundaries: mu can move at most
+            # max_mu_factor fraction of the distance to each extreme
+            mu_lower_bound = (
+                current_fitness - max_mu_factor * dist_to_min
+            )
+            mu_upper_bound = (
+                current_fitness + max_mu_factor * dist_to_max
+            )
+
+            # Ensure boundaries respect absolute limits
+            mu_lower_bound = max(mu_lower_bound, min_fitness)
+            mu_upper_bound = min(mu_upper_bound, max_fitness)
+
+            # Clamp mu to dynamic boundaries
+            mu = min(max(mu, mu_lower_bound), mu_upper_bound)
+        elif not (min_fitness <= mu <= max_fitness):
             raise ValueError(
                 f"mu={mu} not feasible. Must be in "
                 f"[{min_fitness}, {max_fitness}]"
@@ -272,10 +391,15 @@ class BiasedPredictionAgent:
 
         # Check variance feasibility (Bhatia-Davis inequality)
         max_var = (mu - min_fitness) * (max_fitness - mu)
-        if sigma2 > max_var:
-            raise ValueError(
-                f"sigma2={sigma2} not feasible. Must be <= {max_var}"
-            )
+        if not (0 <= sigma2 <= max_var):
+            if self.adjust_sigma2_to_feasible:
+                sigma2 = min(max(sigma2, 0), max_var)
+            else:
+                raise ValueError(
+                    f"sigma2={sigma2} not feasible. Must be <= {max_var}"
+                )
+
+        return mu, sigma2
 
     def solve_constraint_minimization(
         self,