morphml 1.0.0__py3-none-any.whl

morphml/core/search/population.py

@@ -0,0 +1,375 @@
+"""Population management for evolutionary algorithms.
+
+Manages a collection of individuals with selection, sorting, and diversity tracking.
+
+Example:
+    >>> from morphml.core.search import Population, Individual
+    >>>
+    >>> population = Population(max_size=50)
+    >>> population.add(individual1)
+    >>> population.add(individual2)
+    >>>
+    >>> # Get best individuals
+    >>> best = population.get_best(n=10)
+    >>>
+    >>> # Select for breeding
+    >>> parents = population.select(n=20, method='tournament')
+"""
+
+import random
+from typing import Any, Dict, List, Optional
+
+from morphml.core.search.individual import Individual
+from morphml.exceptions import SearchSpaceError
+from morphml.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class Population:
+    """
+    Manages a collection of individuals in evolutionary search.
+
+    Provides methods for:
+    - Adding/removing individuals
+    - Selection strategies
+    - Sorting and filtering
+    - Diversity metrics
+    - Statistics tracking
+
+    Attributes:
+        max_size: Maximum population size
+        individuals: List of Individual instances
+        generation: Current generation number
+        history: Historical statistics
+
+    Example:
+        >>> pop = Population(max_size=100)
+        >>> pop.add_many(initial_individuals)
+        >>> best = pop.get_best(n=10)
+        >>> parents = pop.select(n=20, method='tournament', k=3)
+    """
+
+    def __init__(self, max_size: int = 100, elitism: int = 5):
+        """
+        Initialize population.
+
+        Args:
+            max_size: Maximum population size
+            elitism: Number of best individuals to always keep
+        """
+        self.max_size = max_size
+        self.elitism = elitism
+        self.individuals: List[Individual] = []
+        self.generation = 0
+        self.history: List[Dict[str, Any]] = []
+
+        logger.debug(f"Created Population: max_size={max_size}, elitism={elitism}")
+
+    def add(self, individual: Individual) -> None:
+        """
+        Add an individual to the population.
+
+        Args:
+            individual: Individual to add
+        """
+        self.individuals.append(individual)
+        individual.birth_generation = self.generation
+
+    def add_many(self, individuals: List[Individual]) -> None:
+        """Add multiple individuals."""
+        for ind in individuals:
+            self.add(ind)
+
+    def remove(self, individual: Individual) -> None:
+        """Remove an individual from the population."""
+        if individual in self.individuals:
+            self.individuals.remove(individual)
+
+    def clear(self) -> None:
+        """Remove all individuals."""
+        self.individuals.clear()
+
+    def size(self) -> int:
+        """Get current population size."""
+        return len(self.individuals)
+
+    def is_full(self) -> bool:
+        """Check if population is at maximum size."""
+        return self.size() >= self.max_size
+
+    def get_best(self, n: int = 1) -> List[Individual]:
+        """
+        Get the n best individuals.
+
+        Args:
+            n: Number of individuals to return
+
+        Returns:
+            List of top n individuals sorted by fitness
+        """
+        evaluated = [ind for ind in self.individuals if ind.is_evaluated()]
+        sorted_inds = sorted(evaluated, key=lambda x: x.fitness or 0, reverse=True)
+        return sorted_inds[:n]
+
+    def get_worst(self, n: int = 1) -> List[Individual]:
+        """Get the n worst individuals."""
+        evaluated = [ind for ind in self.individuals if ind.is_evaluated()]
+        sorted_inds = sorted(evaluated, key=lambda x: x.fitness or 0)
+        return sorted_inds[:n]
+
+    def get_unevaluated(self) -> List[Individual]:
+        """Get all unevaluated individuals."""
+        return [ind for ind in self.individuals if not ind.is_evaluated()]
+
+    def select(
+        self,
+        n: int,
+        method: str = "tournament",
+        **kwargs: Any,
+    ) -> List[Individual]:
+        """
+        Select individuals for breeding.
+
+        Args:
+            n: Number of individuals to select
+            method: Selection method ('tournament', 'roulette', 'rank', 'random')
+            **kwargs: Method-specific parameters
+
+        Returns:
+            List of selected individuals
+
+        Example:
+            >>> parents = pop.select(20, method='tournament', k=3)
+        """
+        if method == "tournament":
+            return self._tournament_selection(n, k=kwargs.get("k", 3))
+        elif method == "roulette":
+            return self._roulette_selection(n)
+        elif method == "rank":
+            return self._rank_selection(n)
+        elif method == "random":
+            return self._random_selection(n)
+        else:
+            raise SearchSpaceError(f"Unknown selection method: {method}")
+
+    def _tournament_selection(self, n: int, k: int = 3) -> List[Individual]:
+        """
+        Tournament selection.
+
+        Args:
+            n: Number of individuals to select
+            k: Tournament size
+
+        Returns:
+            Selected individuals
+        """
+        evaluated = [ind for ind in self.individuals if ind.is_evaluated()]
+
+        if len(evaluated) < k:
+            logger.warning(f"Not enough evaluated individuals for tournament size {k}")
+            k = max(1, len(evaluated))
+
+        selected = []
+        for _ in range(n):
+            # Run tournament
+            tournament = random.sample(evaluated, k)
+            winner = max(tournament, key=lambda x: x.fitness or 0)
+            selected.append(winner)
+
+        return selected
+
+    def _roulette_selection(self, n: int) -> List[Individual]:
+        """
+        Roulette wheel selection (fitness-proportionate).
+
+        Args:
+            n: Number of individuals to select
+
+        Returns:
+            Selected individuals
+        """
+        evaluated = [ind for ind in self.individuals if ind.is_evaluated()]
+
+        if not evaluated:
+            return []
+
+        # Shift fitnesses to be positive
+        min_fitness = min(ind.fitness or 0 for ind in evaluated)
+        if min_fitness < 0:
+            fitnesses = [(ind.fitness or 0) - min_fitness + 1e-6 for ind in evaluated]
+        else:
+            fitnesses = [ind.fitness or 1e-6 for ind in evaluated]
+
+        # Normalize to probabilities
+        total_fitness = sum(fitnesses)
+        probabilities = [f / total_fitness for f in fitnesses]
+
+        # Select with replacement
+        selected = random.choices(evaluated, weights=probabilities, k=n)
+
+        return selected
+
+    def _rank_selection(self, n: int) -> List[Individual]:
+        """
+        Rank-based selection.
+
+        Args:
+            n: Number of individuals to select
+
+        Returns:
+            Selected individuals
+        """
+        evaluated = [ind for ind in self.individuals if ind.is_evaluated()]
+
+        if not evaluated:
+            return []
+
+        # Sort by fitness
+        sorted_inds = sorted(evaluated, key=lambda x: x.fitness or 0)
+
+        # Assign ranks (linear ranking)
+        ranks = list(range(1, len(sorted_inds) + 1))
+
+        # Select based on ranks
+        selected = random.choices(sorted_inds, weights=ranks, k=n)
+
+        return selected
+
+    def _random_selection(self, n: int) -> List[Individual]:
+        """Random selection."""
+        evaluated = [ind for ind in self.individuals if ind.is_evaluated()]
+        return random.sample(evaluated, min(n, len(evaluated)))
+
+    def trim(self, target_size: Optional[int] = None) -> None:
+        """
+        Trim population to target size, keeping best individuals.
+
+        Args:
+            target_size: Target size (defaults to max_size)
+        """
+        target_size = target_size or self.max_size
+
+        if self.size() <= target_size:
+            return
+
+        # Always keep elite
+        elite = self.get_best(self.elitism)
+        elite_ids = {ind.id for ind in elite}
+
+        # Get remaining individuals
+        others = [ind for ind in self.individuals if ind.id not in elite_ids]
+
+        # Sort others by fitness
+        others_evaluated = [ind for ind in others if ind.is_evaluated()]
+        [ind for ind in others if not ind.is_evaluated()]
+
+        others_evaluated.sort(key=lambda x: x.fitness or 0, reverse=True)
+
+        # Keep best from others
+        remaining_slots = target_size - len(elite)
+        keep_others = others_evaluated[:remaining_slots]
+
+        # Update population
+        self.individuals = elite + keep_others
+
+        logger.debug(f"Trimmed population to {len(self.individuals)} individuals")
+
+    def increment_ages(self) -> None:
+        """Increment age of all individuals."""
+        for ind in self.individuals:
+            ind.increment_age()
+
+    def next_generation(self) -> None:
+        """Advance to next generation."""
+        self.generation += 1
+        self.increment_ages()
+
+        # Record statistics
+        stats = self.get_statistics()
+        self.history.append(stats)
+
+        logger.info(
+            f"Generation {self.generation}: "
+            f"size={self.size()}, "
+            f"best={stats.get('best_fitness', 0):.4f}, "
+            f"mean={stats.get('mean_fitness', 0):.4f}"
+        )
+
+    def get_statistics(self) -> Dict[str, Any]:
+        """
+        Get population statistics.
+
+        Returns:
+            Dictionary of statistics
+        """
+        evaluated = [ind for ind in self.individuals if ind.is_evaluated()]
+
+        if not evaluated:
+            return {
+                "generation": self.generation,
+                "size": self.size(),
+                "evaluated": 0,
+            }
+
+        fitnesses = [ind.fitness for ind in evaluated if ind.fitness is not None]
+
+        stats = {
+            "generation": self.generation,
+            "size": self.size(),
+            "evaluated": len(evaluated),
+            "best_fitness": max(fitnesses) if fitnesses else 0,
+            "worst_fitness": min(fitnesses) if fitnesses else 0,
+            "mean_fitness": sum(fitnesses) / len(fitnesses) if fitnesses else 0,
+            "median_fitness": sorted(fitnesses)[len(fitnesses) // 2] if fitnesses else 0,
+        }
+
+        return stats
+
+    def get_diversity(self, method: str = "hash") -> float:
+        """
+        Calculate population diversity.
+
+        Args:
+            method: Diversity metric ('hash', 'hamming', 'depth')
+
+        Returns:
+            Diversity score (0-1, higher = more diverse)
+        """
+        if self.size() <= 1:
+            return 0.0
+
+        if method == "hash":
+            # Count unique graph hashes
+            hashes = {ind.graph.hash() for ind in self.individuals}
+            return len(hashes) / self.size()
+
+        elif method == "depth":
+            # Variance in graph depths
+            depths = [ind.graph.get_depth() for ind in self.individuals]
+            if len(set(depths)) == 1:
+                return 0.0
+            mean_depth = sum(depths) / len(depths)
+            variance = sum((d - mean_depth) ** 2 for d in depths) / len(depths)
+            # Normalize
+            return min(1.0, variance / (mean_depth + 1))
+
+        else:
+            return 0.0
+
+    def __len__(self) -> int:
+        """Return population size."""
+        return self.size()
+
+    def __iter__(self) -> Any:
+        """Iterate over individuals."""
+        return iter(self.individuals)
+
+    def __repr__(self) -> str:
+        """String representation."""
+        stats = self.get_statistics()
+        return (
+            f"Population(generation={self.generation}, "
+            f"size={self.size()}/{self.max_size}, "
+            f"best_fitness={stats.get('best_fitness', 0):.4f})"
+        )

morphml/core/search/search_engine.py

@@ -0,0 +1,340 @@
+"""Base search engine for optimization algorithms.
+
+Provides a unified interface for all search/optimization algorithms
+with common functionality for initialization, sampling, and termination.
+
+Author: Eshan Roy <eshanized@proton.me>
+Organization: TONMOY INFRASTRUCTURE & VISION
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Callable, Dict, List, Optional
+
+from morphml.core.dsl.search_space import SearchSpace
+from morphml.core.graph import ModelGraph
+from morphml.core.search.individual import Individual
+from morphml.core.search.population import Population
+from morphml.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class SearchEngine(ABC):
+    """
+    Base class for all search/optimization algorithms.
+
+    Provides common interface and functionality for:
+    - Population initialization
+    - Architecture sampling
+    - Evolution/search steps
+    - History tracking
+    - Termination criteria
+
+    Subclass this to implement specific search algorithms
+    (genetic algorithms, Bayesian optimization, random search, etc.)
+    """
+
+    def __init__(
+        self,
+        search_space: SearchSpace,
+        config: Optional[Dict[str, Any]] = None,
+    ):
+        """
+        Initialize search engine.
+
+        Args:
+            search_space: Search space definition
+            config: Configuration dictionary
+        """
+        self.search_space = search_space
+        self.config = config or {}
+        self.generation = 0
+        self.history: List[Dict[str, Any]] = []
+        self.best_individual: Optional[Individual] = None
+        self.num_evaluations = 0
+
+        logger.info(f"Initialized {self.__class__.__name__}")
+
+    @abstractmethod
+    def initialize_population(self, size: int) -> Population:
+        """
+        Create initial population.
+
+        Args:
+            size: Population size
+
+        Returns:
+            Initialized population
+        """
+        pass
+
+    @abstractmethod
+    def step(self, population: Population, evaluator: Callable) -> Population:
+        """
+        Execute one search iteration.
+
+        Args:
+            population: Current population
+            evaluator: Function to evaluate fitness
+
+        Returns:
+            Updated population after one step
+        """
+        pass
+
+    def should_stop(self) -> bool:
+        """
+        Check if search should terminate.
+
+        Returns:
+            True if termination criteria met
+        """
+        max_generations = self.config.get("max_generations", float("inf"))
+        max_evaluations = self.config.get("max_evaluations", float("inf"))
+
+        if self.generation >= max_generations:
+            logger.info(f"Stopping: reached max generations ({max_generations})")
+            return True
+
+        if self.num_evaluations >= max_evaluations:
+            logger.info(f"Stopping: reached max evaluations ({max_evaluations})")
+            return True
+
+        # Early stopping based on improvement
+        patience = self.config.get("early_stopping_patience", 0)
+        if patience > 0 and len(self.history) >= patience:
+            recent_fitness = [h["best_fitness"] for h in self.history[-patience:]]
+            if len(set(recent_fitness)) == 1:  # No improvement
+                logger.info(f"Stopping: no improvement for {patience} generations")
+                return True
+
+        return False
+
+    def search(
+        self,
+        evaluator: Callable,
+        population_size: int,
+        max_generations: int,
+        callbacks: Optional[List[Callable]] = None,
+    ) -> Individual:
+        """
+        Main search loop.
+
+        Args:
+            evaluator: Function to evaluate fitness
+            population_size: Size of population
+            max_generations: Maximum number of generations
+            callbacks: Optional callbacks to call each generation
+
+        Returns:
+            Best individual found
+
+        Example:
+            >>> engine = MySearchEngine(search_space)
+            >>> best = engine.search(evaluator, population_size=50, max_generations=100)
+        """
+        self.config["max_generations"] = max_generations
+        callbacks = callbacks or []
+
+        logger.info(
+            f"Starting search with population_size={population_size}, max_generations={max_generations}"
+        )
+
+        # Initialize population
+        population = self.initialize_population(population_size)
+
+        # Evaluate initial population
+        self._evaluate_population(population, evaluator)
+
+        # Track best
+        self._update_best(population)
+
+        # Main search loop
+        while not self.should_stop():
+            # Evolution/search step
+            population = self.step(population, evaluator)
+
+            # Evaluate new individuals
+            self._evaluate_population(population, evaluator)
+
+            # Update tracking
+            self._update_best(population)
+            self._record_history(population)
+
+            # Call callbacks
+            for callback in callbacks:
+                callback(self, population)
+
+            # Log progress
+            if self.generation % 10 == 0:
+                stats = self.get_statistics()
+                logger.info(
+                    f"Generation {self.generation}: "
+                    f"best={stats['best_fitness']:.4f}, "
+                    f"mean={stats['mean_fitness']:.4f}, "
+                    f"evaluations={self.num_evaluations}"
+                )
+
+            self.generation += 1
+
+        logger.info(
+            f"Search complete after {self.generation} generations, {self.num_evaluations} evaluations"
+        )
+        logger.info(f"Best fitness: {self.best_individual.fitness:.4f}")
+
+        return self.best_individual
+
+    def _evaluate_population(self, population: Population, evaluator: Callable) -> None:
+        """Evaluate all unevaluated individuals."""
+        for individual in population.individuals:
+            if individual.fitness is None:
+                individual.set_fitness(evaluator(individual.graph))
+                self.num_evaluations += 1
+
+    def _update_best(self, population: Population) -> None:
+        """Update best individual if improvement found."""
+        current_best = population.get_best(1)[0]
+
+        if self.best_individual is None or current_best.fitness > self.best_individual.fitness:
+            self.best_individual = current_best.clone()
+            logger.debug(f"New best: {self.best_individual.fitness:.4f}")
+
+    def _record_history(self, population: Population) -> None:
+        """Record generation statistics."""
+        entry = {
+            "generation": self.generation,
+            "best_fitness": population.best_fitness(),
+            "mean_fitness": population.average_fitness(),
+            "worst_fitness": min(
+                ind.fitness for ind in population.individuals if ind.fitness is not None
+            ),
+            "diversity": population.diversity_metric(),
+            "num_evaluations": self.num_evaluations,
+        }
+        self.history.append(entry)
+
+    def get_statistics(self) -> Dict[str, Any]:
+        """
+        Get current statistics.
+
+        Returns:
+            Dictionary with statistics
+        """
+        if not self.history:
+            return {
+                "generation": 0,
+                "num_evaluations": 0,
+                "best_fitness": 0.0,
+                "mean_fitness": 0.0,
+            }
+
+        latest = self.history[-1]
+        return {
+            "generation": self.generation,
+            "num_evaluations": self.num_evaluations,
+            "best_fitness": latest["best_fitness"],
+            "mean_fitness": latest["mean_fitness"],
+            "diversity": latest["diversity"],
+        }
+
+    def get_best(self) -> ModelGraph:
+        """
+        Get best architecture found.
+
+        Returns:
+            Best ModelGraph
+        """
+        if self.best_individual is None:
+            raise ValueError("No evaluations performed yet")
+
+        return self.best_individual.graph
+
+    def get_best_fitness(self) -> float:
+        """
+        Get best fitness found.
+
+        Returns:
+            Best fitness value
+        """
+        if self.best_individual is None:
+            raise ValueError("No evaluations performed yet")
+
+        return self.best_individual.fitness
+
+    def get_history(self) -> List[Dict[str, Any]]:
+        """
+        Get complete search history.
+
+        Returns:
+            List of generation statistics
+        """
+        return self.history
+
+    def reset(self) -> None:
+        """Reset search engine state."""
+        self.generation = 0
+        self.history = []
+        self.best_individual = None
+        self.num_evaluations = 0
+        logger.info("Search engine reset")
+
+
+class RandomSearchEngine(SearchEngine):
+    """
+    Random search engine (baseline).
+
+    Simply samples random architectures from search space
+    without any guided search.
+
+    Example:
+        >>> engine = RandomSearchEngine(search_space)
+        >>> best = engine.search(evaluator, population_size=1, max_generations=100)
+    """
+
+    def initialize_population(self, size: int) -> Population:
+        """Create initial random population."""
+        individuals = []
+        for _ in range(size):
+            graph = self.search_space.sample()
+            individual = Individual(graph=graph)
+            individuals.append(individual)
+
+        return Population(individuals)
+
+    def step(self, population: Population, evaluator: Callable) -> Population:
+        """Sample new random individuals."""
+        # Replace entire population with new random samples
+        return self.initialize_population(len(population))
+
+
+class GridSearchEngine(SearchEngine):
+    """
+    Grid search engine.
+
+    Systematically explores all combinations of parameter values.
+    Only practical for small discrete search spaces.
+
+    Note: This is a placeholder - full grid search requires
+    combinatorial enumeration of the search space.
+    """
+
+    def __init__(self, search_space: SearchSpace, config: Optional[Dict[str, Any]] = None):
+        """Initialize grid search engine."""
+        super().__init__(search_space, config)
+        self.grid_iterator = None
+
+    def initialize_population(self, size: int) -> Population:
+        """Initialize with first batch from grid."""
+        individuals = []
+        for _ in range(size):
+            graph = self.search_space.sample()
+            individual = Individual(graph=graph)
+            individuals.append(individual)
+
+        return Population(individuals)
+
+    def step(self, population: Population, evaluator: Callable) -> Population:
+        """Get next batch from grid."""
+        # Simplified: just sample randomly
+        # Full implementation would enumerate combinations
+        return self.initialize_population(len(population))