ai-nk-cce 0.1.0__py3-none-any.whl

simulation/hill_climber_simulation.py

@@ -0,0 +1,211 @@
+import logging
+from enum import Enum
+from typing import List, Optional, Type
+
+import numpy as np
+from pydantic import BaseModel
+
+from src.model.config import ParserConfig
+from src.model.dataset import binary_vectors_within_radius
+from src.model.nk_assistant import NKAssistant, NKAssistantConfig
+from src.nk_model.models import NKParams
+from src.nk_model.nk_landscape import NKLandscape
+
+logger = logging.getLogger()
+
+
+class StopCondition(Enum):
+    MAX_ITERATIONS = "max_iterations"
+    REACH_PEAK = "reach_peak"
+
+
+class AgentType(Enum):
+    HILL_CLIMBER = "hill_climber"
+    AI_HILL_CLIMBER = "ai_hill_climber"
+
+    def agent_class(self) -> Type["HillClimberAgent"]:
+        if self == AgentType.HILL_CLIMBER:
+            return HillClimberAgent
+        elif self == AgentType.AI_HILL_CLIMBER:
+            return AIHillClimberAgent
+        else:
+            raise ValueError(f"Invalid agent type: {self}")
+
+
+class HillClimberSimConfig(BaseModel):
+    nk_params: NKParams
+    hamming_distance: int
+    agent_type: AgentType
+    start_idxs: List[int]
+    agent_start_idx: Optional[int] = None
+    use_trajectory: Optional[bool] = False
+    stop_condition: StopCondition
+    stop_condition_kwargs: dict
+
+
+class HillClimberAgent:
+    def __init__(self, start_idx: int):
+        self.trajectory = [start_idx]
+
+    def _get_current_idx(self) -> int:
+        return self.trajectory[-1]
+
+    def hill_climb(
+        self,
+        n: int,
+        hamming_distance: int,
+    ) -> int:
+        neighbors = binary_vectors_within_radius(
+            origin=self._get_current_idx(),
+            radius=hamming_distance,
+            n_dim=n,
+        )
+        next_idx = np.random.choice(neighbors)
+
+        # Only advance if the next index is not in the trajectory
+        if next_idx is not self._get_current_idx():
+            self.trajectory.append(next_idx)
+            return next_idx
+        else:
+            return self.hill_climb(n, hamming_distance)
+
+
+class AIHillClimberAgent(HillClimberAgent):
+    def __init__(self, start_idx: int, use_trajectory: bool):
+        super().__init__(start_idx)
+        self.use_trajectory = use_trajectory
+        assistant_config = NKAssistantConfig(
+            parser_config=ParserConfig(include_payoff=True),
+            use_mpcdf_vllm=True,
+            generation_params={"temperature": 0.7},
+        )
+        self.assistant = NKAssistant(config=assistant_config)
+
+    def hill_climb(
+        self,
+        n: int,
+        k: int,
+        power_scale: float,
+        hamming_distance: int,
+        sample_idxs: List[int],
+        payoffs: List[float],
+    ) -> int:
+        logger.debug(f"sample_idxs: {sample_idxs}")
+        if self.use_trajectory:
+            sample_idxs = self.trajectory
+            logger.debug(f"Using trajectory: {sample_idxs}")
+        else:
+            sample_idxs = sample_idxs[-16:]
+        extracted_payoffs = [payoffs[idx] for idx in sample_idxs]
+        logger.debug(f"extracted_payoffs: {extracted_payoffs}")
+
+        origin_idx = self._get_current_idx()
+        suggestion = self.assistant.suggest(
+            n=n,
+            k=k,
+            power_scale=power_scale,
+            hamming_distance=hamming_distance,
+            sample_idxs=sample_idxs,
+            origin_idx=origin_idx,
+            payoffs=extracted_payoffs,
+        )
+        self.trajectory.append(suggestion)
+        return suggestion
+
+
+class HillClimberSimulation:
+    def __init__(self, config: HillClimberSimConfig):
+        landscape = NKLandscape(params=config.nk_params)
+        self._initialize(config, landscape)
+
+    def _initialize(
+        self, config: HillClimberSimConfig, landscape: NKLandscape
+    ):
+        """Initialize shared components of the simulation.
+
+        Args:
+            config: Configuration for the simulation
+            landscape: The NK landscape instance to use
+        """
+        self.config = config
+        self.visited_idxs = set(config.start_idxs)
+        self.landscape = landscape
+        self.ordered_payoffs = landscape.get_ordered_payoffs()
+
+        # Initialize the agent
+        if (
+            config.agent_start_idx is None
+            or config.agent_start_idx not in config.start_idxs
+        ):
+            self.agent_start_idx = np.random.choice(config.start_idxs)
+        else:
+            self.agent_start_idx = config.agent_start_idx
+
+        if config.agent_type == AgentType.HILL_CLIMBER:
+            self.agent = HillClimberAgent(start_idx=self.agent_start_idx)
+        elif config.agent_type == AgentType.AI_HILL_CLIMBER:
+            self.agent = AIHillClimberAgent(
+                start_idx=self.agent_start_idx,
+                use_trajectory=config.use_trajectory,
+            )
+
+    @classmethod
+    def from_cached_landscape(
+        cls, config: HillClimberSimConfig, landscape_uuid: str
+    ) -> "HillClimberSimulation":
+        """Create simulation using a cached landscape by UUID.
+
+        Args:
+            config: Configuration for the simulation
+            landscape_uuid: UUID of the cached landscape to use
+
+        Returns:
+            HillClimberSimulation instance with the cached landscape
+        """
+        instance = cls.__new__(cls)
+        landscape = NKLandscape.from_cache(landscape_uuid)
+        instance._initialize(config, landscape)
+        return instance
+
+    def run(self):
+        while not self._break_hill_climber(self.agent.trajectory):
+            if self.config.agent_type == AgentType.HILL_CLIMBER:
+                self.agent.hill_climb(
+                    n=self.config.nk_params.n,
+                    hamming_distance=self.config.hamming_distance,
+                )
+            elif self.config.agent_type == AgentType.AI_HILL_CLIMBER:
+                self.agent.hill_climb(
+                    n=self.config.nk_params.n,
+                    k=self.config.nk_params.k,
+                    power_scale=self.config.nk_params.power,
+                    hamming_distance=self.config.hamming_distance,
+                    sample_idxs=list(self.visited_idxs),
+                    payoffs=self.ordered_payoffs,
+                )
+            # Update visited indices
+            self.visited_idxs.update(self.agent.trajectory)
+            logger.debug(f"visited_idxs: {self.visited_idxs}")
+
+        return self.agent.trajectory
+
+    def _break_hill_climber(self, trajectory: List[int]) -> bool:
+        if self.config.stop_condition == StopCondition.MAX_ITERATIONS:
+            # Break if the number of iterations where reached
+            return (
+                len(trajectory)
+                >= self.config.stop_condition_kwargs["max_iterations"]
+            )
+        elif self.config.stop_condition == StopCondition.REACH_PEAK:
+            # Break if the agent is stuck on a local maximum
+            stuck_for_until_break = self.config.stop_condition_kwargs[
+                "stuck_for_until_break"
+            ]
+            if len(trajectory) < stuck_for_until_break * 2:
+                return False
+            if set(trajectory[:-stuck_for_until_break]) >= set(
+                trajectory[-stuck_for_until_break:]
+            ):
+                return True
+            else:
+                return False

simulation/hill_climber_vs_ai_simulation.py

@@ -0,0 +1,132 @@
+import numpy as np
+from tqdm.auto import tqdm
+
+from src.nk_model.models import NKParams
+from src.nk_model.nk_landscape import NKLandscape
+from src.simulation.hill_climber_simulation import (
+    AgentType,
+    HillClimberSimConfig,
+    HillClimberSimulation,
+    StopCondition,
+)
+
+
+def hill_climber_vs_ai_simulation(
+    config: HillClimberSimConfig,
+    landscape: NKLandscape,
+):
+    if config.agent_start_idx is None:
+        config.agent_start_idx = np.random.choice(config.start_idxs)
+
+    if config.agent_type == AgentType.HILL_CLIMBER:
+        hill_climber_config = config
+        ai_config = config.model_copy(
+            update={"agent_type": AgentType.AI_HILL_CLIMBER}
+        )
+    elif config.agent_type == AgentType.AI_HILL_CLIMBER:
+        ai_config = config
+        hill_climber_config = config.model_copy(
+            update={"agent_type": AgentType.HILL_CLIMBER}
+        )
+
+    hill_climber_simulation = HillClimberSimulation.from_cached_landscape(
+        config=hill_climber_config, landscape_uuid=landscape.uuid
+    )
+    ai_simulation = HillClimberSimulation.from_cached_landscape(
+        config=ai_config, landscape_uuid=landscape.uuid
+    )
+
+    hill_climber_trajectory = hill_climber_simulation.run()
+    ai_trajectory = ai_simulation.run()
+
+    return hill_climber_trajectory, ai_trajectory
+
+
+def compare_hill_climber_vs_ai(
+    nk_params: NKParams,
+    hamming_distance: int,
+    max_iterations: int,
+    repetitions: int,
+    n_start_idxs: int = 1,
+):
+    hill_climber_payoff_trajectories = []
+    ai_payoff_trajectories = []
+    for _ in tqdm(range(repetitions), desc="Comparing hill climber vs AI"):
+        start_idxs = [
+            np.random.choice(list(range(2**nk_params.n)))
+            for _ in range(n_start_idxs)
+        ]
+        start_idx = np.random.choice(start_idxs)
+
+        config = HillClimberSimConfig(
+            nk_params=nk_params,
+            agent_type=AgentType.HILL_CLIMBER,
+            start_idxs=start_idxs,
+            agent_start_idx=start_idx,
+            use_trajectory=True,
+            stop_condition=StopCondition.MAX_ITERATIONS,
+            stop_condition_kwargs={"max_iterations": max_iterations},
+            hamming_distance=hamming_distance,
+        )
+        landscape = NKLandscape(params=nk_params)
+        payoff_list = landscape.get_ordered_payoffs()
+
+        hill_climber_trajectory, ai_trajectory = hill_climber_vs_ai_simulation(
+            config, landscape
+        )
+
+        hill_climber_payoff_traj = [
+            payoff_list[idx] for idx in hill_climber_trajectory
+        ]
+        ai_payoff_traj = [payoff_list[idx] for idx in ai_trajectory]
+
+        hill_climber_payoff_trajectories.append(hill_climber_payoff_traj)
+        ai_payoff_trajectories.append(ai_payoff_traj)
+
+    return hill_climber_payoff_trajectories, ai_payoff_trajectories
+
+
+def average_payoff_trajectories(
+    payoff_trajectories: list[list[float]],
+) -> list[float]:
+    """Transform list of payoff trajectories into list of averaged payoffs.
+
+    Args:
+        payoff_trajectories: List of payoff trajectories, where each
+            trajectory is a list of payoffs.
+
+    Returns:
+        List of averaged payoffs at each step position.
+    """
+    if not payoff_trajectories:
+        return []
+
+    max_len = max(len(traj) for traj in payoff_trajectories)
+    averaged = []
+
+    for step_idx in range(max_len):
+        step_payoffs = [
+            traj[step_idx]
+            for traj in payoff_trajectories
+            if step_idx < len(traj)
+        ]
+        averaged.append(np.mean(step_payoffs))
+
+    return averaged
+
+
+def average_last_payoff(payoff_trajectories: list[list[float]]) -> float:
+    """Return the average of the last payoff in each trajectory.
+
+    Args:
+        payoff_trajectories: List of payoff trajectories, where each
+            trajectory is a list of payoffs.
+
+    Returns:
+        Average of the last payoff across all trajectories.
+    """
+    if not payoff_trajectories:
+        return 0.0
+
+    last_payoffs = [traj[-1] for traj in payoff_trajectories if traj]
+    return np.mean(last_payoffs)

simulation/landscape_selection.py

@@ -0,0 +1,179 @@
+"""Utilities for finding and selecting average performing landscapes."""
+
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import List, Tuple
+
+import numpy as np
+from tqdm import tqdm
+
+from src.nk_model.models import NKParams
+from src.nk_model.nk_landscape import NKLandscape
+from src.simulation.hill_climber_simulation import (
+    AgentType,
+    HillClimberSimConfig,
+    HillClimberSimulation,
+    StopCondition,
+)
+
+
+def run_simulation_with_landscape(
+    landscape_uuid: str,
+    nk_params: NKParams,
+    hamming_distance: int,
+    max_iterations: int,
+) -> float:
+    """Run simulation on a specific landscape and return final payoff.
+
+    Args:
+        landscape_uuid: UUID of the cached landscape
+        nk_params: NK model parameters
+        hamming_distance: Hamming distance for neighbor selection
+        max_iterations: Maximum number of iterations
+        start_idxs: List of starting indices
+
+    Returns:
+        Final payoff from the simulation
+    """
+
+    start_idxs = np.random.choice(list(range(2**nk_params.n)), 1)
+
+    config = HillClimberSimConfig(
+        nk_params=nk_params,
+        agent_type=AgentType.HILL_CLIMBER,
+        start_idxs=start_idxs,
+        stop_condition=StopCondition.MAX_ITERATIONS,
+        stop_condition_kwargs={"max_iterations": max_iterations},
+        hamming_distance=hamming_distance,
+    )
+
+    simulation = HillClimberSimulation.from_cached_landscape(
+        config=config, landscape_uuid=landscape_uuid
+    )
+    trajectory = simulation.run()
+
+    final_idx = trajectory[-1]
+    final_payoff = simulation.ordered_payoffs[final_idx]
+
+    return final_payoff
+
+
+def select_average_landscape(
+    results: List[Tuple[str, float]],
+    percentile_low: float = 25.0,
+    percentile_high: float = 75.0,
+) -> str:
+    """Select an average landscape from tested results.
+
+    Args:
+        results: List of tuples (landscape_uuid, average_payoff)
+        percentile_low: Lower percentile threshold (default: 25.0)
+        percentile_high: Upper percentile threshold (default: 75.0)
+
+    Returns:
+        UUID of the selected landscape
+    """
+    # Sort by average payoff
+    results.sort(key=lambda x: x[1])
+
+    # Select from percentile range
+    start_idx = int((percentile_low / 100.0) * len(results))
+    end_idx = int((percentile_high / 100.0) * len(results))
+    candidates = results[start_idx:end_idx]
+
+    # Randomly select one landscape
+    selected_idx = np.random.choice(range(len(candidates)))
+    return candidates[selected_idx][0]
+
+
+def find_average_landscape_for_k(
+    nk_params: NKParams,
+    num_landscapes: int = 100,
+    repetitions: int = 100,
+    hamming_distance: int = 1,
+    max_iterations: int = 10,
+) -> str:
+    """Find an average landscape for a specific k value.
+
+    Args:
+        nk_params: NK model parameters
+        num_landscapes: Number of landscapes to generate and test
+        repetitions: Number of repetitions per landscape
+        hamming_distance: Hamming distance for neighbor selection
+        max_iterations: Maximum number of iterations
+
+    Returns:
+        UUID of the selected average landscape
+    """
+
+    # Generate landscapes
+    landscape_uuids = [
+        NKLandscape(params=nk_params).uuid for _ in range(num_landscapes)
+    ]
+
+    # Test landscapes and collect results
+    results = []
+    for uuid in tqdm(landscape_uuids, desc="Testing landscapes"):
+        final_payoffs = []
+        for _ in range(repetitions):
+            payoff = run_simulation_with_landscape(
+                landscape_uuid=uuid,
+                nk_params=nk_params,
+                hamming_distance=hamming_distance,
+                max_iterations=max_iterations,
+            )
+            final_payoffs.append(payoff)
+        avg_payoff = np.mean(final_payoffs)
+        results.append((uuid, avg_payoff))
+
+    # Select average landscape
+    selected_uuid = select_average_landscape(results)
+
+    return selected_uuid
+
+
+def save_landscape_json(
+    landscape_uuid: str,
+    output_path: Path,
+    n: int,
+    k: int,
+    add_timestamp: bool = True,
+) -> Path:
+    """Save a landscape to disk as JSON.
+
+    Args:
+        landscape_uuid: UUID of the landscape to save
+        output_path: Path where to save the JSON file
+        n: Number of components
+        k: Number of interactions
+        add_timestamp: Whether to add timestamp to filename
+
+    Returns:
+        Path to the saved file (with timestamp if added)
+    """
+    landscape = NKLandscape.from_cache(landscape_uuid)
+    json_data = []
+    nk_str = f"({n}, {k})"
+
+    for item in landscape.items:
+        location = "".join([str(int(coord)) for coord in item.coordinates])
+        fitness = int(item.payoff)
+
+        json_data.append(
+            {"N_NK": nk_str, "location": location, "fitness": fitness}
+        )
+
+    # Add timestamp to filename if requested
+    if add_timestamp:
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        stem = output_path.stem
+        suffix = output_path.suffix
+        output_path = output_path.parent / f"{stem}_{timestamp}{suffix}"
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    print(f"Saving landscape to {output_path}")
+    with open(output_path, "w") as f:
+        json.dump(json_data, f, indent=4)
+
+    return output_path

utils/binary_conversion.py

@@ -0,0 +1,128 @@
+"""Binary conversion utilities for transforming between int, array, and string.
+
+This module provides functions to convert between different representations
+of binary states:
+- Integer (0-255): Represents an 8-bit binary number
+- Binary array: NumPy array of shape (8,) with values 0 or 1
+- Binary string: String representation like "0,0,0,0,0,0,0,0"
+"""
+
+import numpy as np
+
+from src.utils.utils import BIN_ARRAY
+
+
+def int_to_binary_str(value: int, separator: str = ",") -> str:
+    """Convert integer to binary string representation.
+
+    Args:
+        value: Integer value (0-255) to convert
+        separator: String separator for binary digits. Defaults to ",".
+
+    Returns:
+        Binary string representation, e.g., "0,0,0,0,0,0,0,0"
+
+    Examples:
+        >>> int_to_binary_str(0)
+        '0,0,0,0,0,0,0,0'
+        >>> int_to_binary_str(255)
+        '1,1,1,1,1,1,1,1'
+        >>> int_to_binary_str(15)
+        '0,0,0,0,1,1,1,1'
+    """
+    return separator.join([str(v) for v in BIN_ARRAY[value]])
+
+
+def binary_str_to_int(binary_str: str, separator: str = ",") -> int:
+    """Convert binary string to integer.
+
+    Args:
+        binary_str: Binary string representation, e.g., "0,0,0,0,0,0,0,0"
+        separator: String separator used in binary_str. Defaults to ",".
+
+    Returns:
+        Integer value (0-255)
+
+    Examples:
+        >>> binary_str_to_int("0,0,0,0,0,0,0,0")
+        0
+        >>> binary_str_to_int("1,1,1,1,1,1,1,1")
+        255
+        >>> binary_str_to_int("0,0,0,0,1,1,1,1")
+        15
+    """
+    return int(binary_str.replace(separator, ""), 2)
+
+
+def int_to_binary_array(value: int) -> np.ndarray:
+    """Convert integer to binary array.
+
+    Args:
+        value: Integer value (0-255) to convert
+
+    Returns:
+        Binary array of shape (8,) with values 0 or 1
+
+    Examples:
+        >>> int_to_binary_array(0)
+        array([0, 0, 0, 0, 0, 0, 0, 0])
+        >>> int_to_binary_array(255)
+        array([1, 1, 1, 1, 1, 1, 1, 1])
+    """
+    return BIN_ARRAY[value].copy()
+
+
+def binary_array_to_int(binary_array: np.ndarray) -> int:
+    """Convert binary array to integer.
+
+    Args:
+        binary_array: Binary array of shape (8,) with values 0 or 1
+
+    Returns:
+        Integer value (0-255)
+
+    Examples:
+        >>> binary_array_to_int(np.array([0, 0, 0, 0, 0, 0, 0, 0]))
+        0
+        >>> binary_array_to_int(np.array([1, 1, 1, 1, 1, 1, 1, 1]))
+        255
+    """
+    return int("".join([str(int(v)) for v in binary_array]), 2)
+
+
+def binary_array_to_str(binary_array: np.ndarray, separator: str = ",") -> str:
+    """Convert binary array to string representation.
+
+    Args:
+        binary_array: Binary array of shape (n,) with values 0 or 1
+        separator: String separator for binary digits. Defaults to ",".
+
+    Returns:
+        Binary string representation, e.g., "1,0,1,0,1"
+
+    Examples:
+        >>> binary_array_to_str(np.array([1, 0, 1, 0, 1]))
+        '1,0,1,0,1'
+        >>> binary_array_to_str(np.array([1, 0, 1]), separator=" ")
+        '1 0 1'
+    """
+    return separator.join([str(int(item)) for item in binary_array])
+
+
+def binary_str_to_array(binary_str: str, separator: str = ",") -> np.ndarray:
+    """Convert binary string to array.
+
+    Args:
+        binary_str: Binary string representation, e.g., "0,0,0,0,0,0,0,0"
+        separator: String separator used in binary_str. Defaults to ",".
+
+    Returns:
+        Binary array of shape (n,) with values 0 or 1
+
+    Examples:
+        >>> binary_str_to_array("0,0,0,0,0,0,0,0")
+        array([0, 0, 0, 0, 0, 0, 0, 0])
+        >>> binary_str_to_array("1,1,1,1,1,1,1,1")
+        array([1, 1, 1, 1, 1, 1, 1, 1])
+    """
+    return np.array([int(x) for x in binary_str.split(separator)])

utils/logging.py

@@ -0,0 +1,33 @@
+import functools
+import logging
+from time import time
+
+# logging settings
+logging.basicConfig(
+    format=("%(asctime)s %(levelname)-8s %(message)s"),
+    # log.INFO for normal run
+    level=logging.INFO,
+    # log.DEBUG for diagnostics
+    # level=logging.DEBUG,
+    datefmt="%Y-%m-%d %H:%M:%S",
+)
+
+
+def log_dec(func):
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        logger = logging.getLogger(func.__module__)
+        try:
+            start_time = time()
+            logger.info("%-30s started", func.__name__)
+            return func(*args, **kwargs)
+        except Exception as ex:
+            logger.error(f"%-30s raised an exception: {ex}", func.__name__)
+            raise ex
+        finally:
+            duration = time() - start_time
+            logger.info(
+                "%-30s finished in %s seconds", func.__name__, duration
+            )
+
+    return wrapper