ctrl-freak 0.1.0__py3-none-any.whl

ctrl_freak/selection/roulette.py

@@ -0,0 +1,115 @@
+"""Roulette wheel (fitness-proportionate) selection for single-objective optimization."""
+
+import numpy as np
+
+from ctrl_freak.population import Population
+
+
+def roulette_wheel():
+    """Create a roulette wheel (fitness-proportionate) parent selector.
+
+    Selection probability is inversely proportional to fitness because
+    lower fitness is better (minimization). Uses max_fitness - fitness
+    to convert minimization to maximization probabilities.
+
+    For fitness values f_i, the selection probability p_i is computed as:
+        weights_i = max_fitness - f_i + ε
+        p_i = weights_i / Σ(weights_j)
+
+    where ε is a small constant to ensure the worst individual has non-zero probability.
+
+    Returns
+    -------
+    callable
+        Parent selector that performs fitness-proportionate selection.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from ctrl_freak.population import Population
+    >>> from ctrl_freak.selection.roulette import roulette_wheel
+    >>> pop = Population(x=np.zeros((4, 2)), objectives=np.array([[4.0], [1.0], [2.0], [3.0]]))
+    >>> selector = roulette_wheel()
+    >>> parents = selector(pop, 5, np.random.default_rng(0))
+    >>> parents.shape
+    (5,)
+    """
+
+    def selector(
+        pop: Population,
+        n_parents: int,
+        rng: np.random.Generator,
+        **kwargs: np.ndarray,
+    ) -> np.ndarray:
+        """Select parents using fitness-proportionate (roulette wheel) selection.
+
+        Parameters
+        ----------
+        pop
+            Population to select from.
+        n_parents
+            Number of parents to select.
+        rng
+            Random number generator.
+        **kwargs
+            Optional ``fitness`` array. If omitted, fitness is extracted from a
+            single-objective population.
+
+        Returns
+        -------
+        numpy.ndarray
+            Selected parent indices with shape ``(n_parents,)`` and dtype
+            ``np.intp``.
+
+        Raises
+        ------
+        ValueError
+            If no valid fitness source is available.
+
+        Examples
+        --------
+        >>> import numpy as np
+        >>> from ctrl_freak.population import Population
+        >>> from ctrl_freak.selection.roulette import roulette_wheel
+        >>> pop = Population(x=np.zeros((3, 1)), objectives=np.array([[3.0], [1.0], [2.0]]))
+        >>> selector = roulette_wheel()
+        >>> out = selector(pop, 4, np.random.default_rng(2))
+        >>> out.shape
+        (4,)
+        """
+        # Get fitness array
+        if "fitness" in kwargs:
+            fitness = kwargs["fitness"]
+        elif pop.objectives is not None and pop.objectives.shape[1] == 1:
+            # Extract from single-column objectives
+            fitness = pop.objectives[:, 0]
+        else:
+            raise ValueError(
+                "roulette wheel selection requires 'fitness' in kwargs or single-column objectives in population"
+            )
+
+        pop_size = len(pop)
+
+        # Handle edge case: all equal fitness -> uniform selection
+        if np.all(fitness == fitness[0]):
+            # All individuals have equal fitness, select uniformly
+            return rng.choice(pop_size, size=n_parents, replace=True).astype(np.intp)
+
+        # Convert minimization to maximization: lower fitness -> higher selection probability
+        # Use max - fitness approach to avoid division by near-zero values
+        max_fitness = np.max(fitness)
+        epsilon = 1e-10  # Small constant to handle max fitness case
+
+        # Compute selection weights: (max_fitness - fitness + epsilon)
+        # This ensures the best individual (lowest fitness) gets highest weight
+        weights = max_fitness - fitness + epsilon
+
+        # Normalize to probabilities
+        probs = weights / weights.sum()
+
+        # Select n_parents indices with replacement using roulette wheel
+        selected = rng.choice(pop_size, size=n_parents, replace=True, p=probs)
+
+        return selected.astype(np.intp)
+
+    return selector

ctrl_freak/selection/tournament.py

@@ -0,0 +1,104 @@
+"""Fitness tournament selection for single-objective optimization."""
+
+import numpy as np
+
+from ctrl_freak.population import Population
+
+
+def fitness_tournament(tournament_size: int = 2):
+    """Create a fitness-based tournament parent selector for single-objective optimization.
+
+    Parameters
+    ----------
+    tournament_size
+        Number of individuals competing in each tournament.
+
+    Returns
+    -------
+    callable
+        Parent selector that returns selected parent indices.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from ctrl_freak.population import Population
+    >>> from ctrl_freak.selection.tournament import fitness_tournament
+    >>> pop = Population(x=np.zeros((4, 2)), objectives=np.array([[3.0], [1.0], [2.0], [4.0]]))
+    >>> selector = fitness_tournament(tournament_size=2)
+    >>> parents = selector(pop, 5, np.random.default_rng(0))
+    >>> parents.shape
+    (5,)
+    """
+
+    def selector(
+        pop: Population,
+        n_parents: int,
+        rng: np.random.Generator,
+        **kwargs: np.ndarray,
+    ) -> np.ndarray:
+        """Select parents using fitness tournament selection.
+
+        Parameters
+        ----------
+        pop
+            Population to select from.
+        n_parents
+            Number of parents to select.
+        rng
+            Random number generator.
+        **kwargs
+            Optional ``fitness`` array. If omitted, fitness is extracted from a
+            single-objective population.
+
+        Returns
+        -------
+        numpy.ndarray
+            Selected parent indices.
+
+        Raises
+        ------
+        ValueError
+            If no valid fitness source is available.
+
+        Examples
+        --------
+        >>> import numpy as np
+        >>> from ctrl_freak.population import Population
+        >>> from ctrl_freak.selection.tournament import fitness_tournament
+        >>> pop = Population(x=np.zeros((3, 1)), objectives=np.array([[2.0], [1.0], [3.0]]))
+        >>> selector = fitness_tournament()
+        >>> out = selector(pop, 4, np.random.default_rng(2))
+        >>> out.shape
+        (4,)
+        """
+        # Get fitness array
+        if "fitness" in kwargs:
+            fitness = kwargs["fitness"]
+        elif pop.objectives is not None and pop.objectives.shape[1] == 1:
+            # Extract from single-column objectives
+            fitness = pop.objectives[:, 0]
+        else:
+            raise ValueError(
+                "fitness tournament selection requires 'fitness' in kwargs or single-column objectives in population"
+            )
+
+        pop_size = len(pop)
+
+        # Select n_parents winners via tournament
+        selected = np.empty(n_parents, dtype=np.intp)
+
+        for i in range(n_parents):
+            # Pick tournament_size random individuals
+            candidates = rng.integers(0, pop_size, size=tournament_size)
+
+            # Find winner: prefer lower fitness (minimization)
+            best_idx = candidates[0]
+            for c in candidates[1:]:
+                if fitness[c] < fitness[best_idx]:
+                    best_idx = c
+
+            selected[i] = best_idx
+
+        return selected
+
+    return selector

ctrl_freak/survival/__init__.py

@@ -0,0 +1,13 @@
+"""Survival strategies for evolutionary algorithms."""
+
+from ctrl_freak.registry import SurvivalRegistry
+from ctrl_freak.survival.elitist import elitist_survival
+from ctrl_freak.survival.nsga2 import nsga2_survival
+from ctrl_freak.survival.truncation import truncation_survival
+
+# Register built-in survival strategies
+SurvivalRegistry.register("elitist", elitist_survival)
+SurvivalRegistry.register("nsga2", nsga2_survival)
+SurvivalRegistry.register("truncation", truncation_survival)
+
+__all__ = ["elitist_survival", "nsga2_survival", "truncation_survival"]

ctrl_freak/survival/elitist.py

@@ -0,0 +1,147 @@
+"""Elitist survival selection for single-objective optimization."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ctrl_freak.population import Population
+
+
+def elitist_survival(elite_count: int = 1):
+    """Create elitist survivor selector.
+
+    Elitist survival always keeps the best `elite_count` individuals from the
+    parent population, filling remaining slots with the best offspring.
+
+    Parameters
+    ----------
+    elite_count
+        Number of elite parents to preserve.
+
+    Returns
+    -------
+    callable
+        Survivor selector function.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from ctrl_freak.population import Population
+    >>> from ctrl_freak.survival.elitist import elitist_survival
+    >>> obj = np.array([[2.0], [1.0], [4.0], [0.5]])
+    >>> pop = Population(x=np.zeros((4, 1)), objectives=obj)
+    >>> indices, state = elitist_survival(elite_count=1)(pop, 2, parent_size=2)
+    >>> indices.shape
+    (2,)
+    >>> state["fitness"].shape
+    (2,)
+    """
+    if elite_count <= 0:
+        raise ValueError(f"elite_count must be positive, got {elite_count}")
+
+    def selector(
+        pop: Population,
+        n_survivors: int,
+        **kwargs: np.ndarray,
+    ) -> tuple[np.ndarray, dict[str, np.ndarray]]:
+        """Select survivors using elitist selection.
+
+        Parameters
+        ----------
+        pop
+            Combined parent and offspring population.
+        n_survivors
+            Number of survivors to select.
+        **kwargs
+            Must include ``parent_size``. May include explicit ``fitness``.
+
+        Returns
+        -------
+        tuple[numpy.ndarray, dict[str, numpy.ndarray]]
+            Selected indices and state containing the selected ``fitness`` values.
+
+        Raises
+        ------
+        ValueError
+            If inputs are invalid or no valid fitness source is available.
+
+        Examples
+        --------
+        >>> import numpy as np
+        >>> from ctrl_freak.population import Population
+        >>> from ctrl_freak.survival.elitist import elitist_survival
+        >>> obj = np.array([[2.0], [1.0], [4.0], [3.0], [0.5], [1.5]])
+        >>> pop = Population(x=np.zeros((6, 1)), objectives=obj)
+        >>> indices, state = elitist_survival(elite_count=1)(pop, 3, parent_size=3)
+        >>> indices
+        array([1, 4, 5])
+        >>> state["fitness"].shape
+        (3,)
+        """
+        # Validate n_survivors
+        if n_survivors <= 0:
+            raise ValueError(f"n_survivors must be positive, got {n_survivors}")
+        if n_survivors > len(pop):
+            raise ValueError(f"n_survivors ({n_survivors}) cannot exceed population size ({len(pop)})")
+
+        # Validate parent_size kwarg
+        parent_size = kwargs.get("parent_size")
+        if parent_size is None:
+            raise ValueError(
+                "elitist survival requires 'parent_size' kwarg to distinguish "
+                "parents from offspring in the combined population"
+            )
+        if not isinstance(parent_size, (int, np.integer)):
+            raise ValueError(f"parent_size must be an integer, got {type(parent_size)}")
+        if parent_size <= 0:
+            raise ValueError(f"parent_size must be positive, got {parent_size}")
+        if parent_size > len(pop):
+            raise ValueError(f"parent_size ({parent_size}) cannot exceed population size ({len(pop)})")
+
+        # Validate elite_count constraints
+        if elite_count > parent_size:
+            raise ValueError(f"elite_count ({elite_count}) cannot exceed parent_size ({parent_size})")
+        if elite_count > n_survivors:
+            raise ValueError(f"elite_count ({elite_count}) cannot exceed n_survivors ({n_survivors})")
+
+        # Get fitness values
+        fitness = kwargs.get("fitness")
+        if fitness is None:
+            if pop.objectives is None:
+                raise ValueError("Population must have objectives computed for survivor selection")
+            if pop.objectives.shape[1] != 1:
+                raise ValueError(
+                    f"elitist survival requires single-objective optimization "
+                    f"(got {pop.objectives.shape[1]} objectives). "
+                    "Pass explicit 'fitness' kwarg for multi-objective."
+                )
+            fitness = pop.objectives[:, 0]
+
+        # Split population into parents and offspring
+        parent_fitness = fitness[:parent_size]
+        offspring_fitness = fitness[parent_size:]
+
+        # Select elite parents (best elite_count from parents)
+        # Use stable sort for deterministic tie-breaking
+        parent_sorted_indices = np.argsort(parent_fitness, kind="stable")
+        elite_indices = parent_sorted_indices[:elite_count].astype(np.intp)
+
+        # Select best offspring to fill remaining slots
+        n_offspring_needed = n_survivors - elite_count
+        if n_offspring_needed > 0:
+            # Use stable sort for deterministic tie-breaking
+            offspring_sorted_indices = np.argsort(offspring_fitness, kind="stable")
+            # Map back to original indices in combined population
+            best_offspring_indices = (offspring_sorted_indices[:n_offspring_needed] + parent_size).astype(np.intp)
+
+            # Combine elite parents and best offspring
+            survivor_indices = np.concatenate([elite_indices, best_offspring_indices])
+        else:
+            survivor_indices = elite_indices
+
+        # Compute state for survivors
+        survivor_fitness = fitness[survivor_indices].copy()
+
+        return survivor_indices, {"fitness": survivor_fitness}
+
+    return selector

ctrl_freak/survival/nsga2.py

@@ -0,0 +1,140 @@
+"""NSGA-II survivor selection strategy.
+
+Examples
+--------
+>>> import numpy as np
+>>> from ctrl_freak.population import Population
+>>> from ctrl_freak.survival.nsga2 import nsga2_survival
+>>> obj = np.array([[1.0, 4.0], [2.0, 3.0], [3.0, 2.0], [4.0, 1.0]])
+>>> pop = Population(x=np.zeros((4, 1)), objectives=obj)
+>>> selector = nsga2_survival()
+>>> indices, state = selector(pop, n_survivors=2)
+>>> indices.shape
+(2,)
+>>> sorted(state)
+['crowding_distance', 'rank']
+"""
+
+import numpy as np
+
+from ctrl_freak.population import Population
+from ctrl_freak.primitives import crowding_distance, non_dominated_sort
+
+
+def nsga2_survival():
+    """Create NSGA-II survivor selector.
+
+    The NSGA-II survival strategy implements elitist selection by:
+    1. Computing Pareto ranks using non-dominated sorting
+    2. Filling survivors front-by-front in rank order
+    3. When a front only partially fits, selecting individuals with highest
+       crowding distance (most isolated in objective space)
+
+    This preserves both convergence (keeping better fronts) and diversity
+    (preferring isolated individuals within a front).
+
+    Returns
+    -------
+    callable
+        Survivor selector that returns selected indices and rank/crowding state.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from ctrl_freak.population import Population
+    >>> from ctrl_freak.survival.nsga2 import nsga2_survival
+    >>> obj = np.array([[1.0, 4.0], [2.0, 3.0], [3.0, 2.0], [4.0, 1.0]])
+    >>> pop = Population(x=np.zeros((4, 1)), objectives=obj)
+    >>> selector = nsga2_survival()
+    >>> indices, state = selector(pop, n_survivors=2)
+    >>> indices.shape
+    (2,)
+    >>> sorted(state)
+    ['crowding_distance', 'rank']
+    """
+
+    def selector(
+        pop: Population,
+        n_survivors: int,
+        **kwargs: np.ndarray,
+    ) -> tuple[np.ndarray, dict[str, np.ndarray]]:
+        """Select survivors using NSGA-II crowded selection.
+
+        Parameters
+        ----------
+        pop
+            Population to select from.
+        n_survivors
+            Number of survivors to select.
+        **kwargs
+            Unused keyword arguments.
+
+        Returns
+        -------
+        tuple[numpy.ndarray, dict[str, numpy.ndarray]]
+            Selected indices and state containing ``rank`` and
+            ``crowding_distance`` arrays.
+
+        Raises
+        ------
+        ValueError
+            If objectives are missing or ``n_survivors`` is invalid.
+
+        Examples
+        --------
+        >>> import numpy as np
+        >>> from ctrl_freak.population import Population
+        >>> from ctrl_freak.survival.nsga2 import nsga2_survival
+        >>> obj = np.array([[1.0, 3.0], [2.0, 2.0], [3.0, 1.0]])
+        >>> pop = Population(x=np.zeros((3, 1)), objectives=obj)
+        >>> indices, state = nsga2_survival()(pop, n_survivors=2)
+        >>> indices.shape
+        (2,)
+        >>> state["rank"].shape
+        (2,)
+        """
+        if pop.objectives is None:
+            raise ValueError("Population must have objectives computed for survivor selection")
+        if n_survivors <= 0:
+            raise ValueError(f"n_survivors must be positive, got {n_survivors}")
+        if n_survivors > len(pop):
+            raise ValueError(f"n_survivors ({n_survivors}) cannot exceed population size ({len(pop)})")
+
+        # Compute ranks for entire population
+        all_ranks = non_dominated_sort(pop.objectives)
+
+        # Fill survivors front-by-front, caching crowding distance as we go.
+        selected: list[int] = []
+        selected_cd_parts: list[np.ndarray] = []
+        current_rank = 0
+
+        while len(selected) < n_survivors:
+            front_idx = np.where(all_ranks == current_rank)[0]
+
+            if len(selected) + len(front_idx) <= n_survivors:
+                # Whole front fits: crowding over the full front equals crowding over the
+                # selected subset, so cache it directly.
+                selected.extend(front_idx.tolist())
+                selected_cd_parts.append(crowding_distance(pop.objectives[front_idx]))
+            else:
+                # Critical front: select by full-front crowding, then recompute over the
+                # selected subset to match the prior returned-state semantics.
+                remaining = n_survivors - len(selected)
+                cd = crowding_distance(pop.objectives[front_idx])
+                top_cd_indices = np.argsort(cd)[::-1][:remaining]
+                chosen = front_idx[top_cd_indices]
+                selected.extend(chosen.tolist())
+                selected_cd_parts.append(crowding_distance(pop.objectives[chosen]))
+
+            current_rank += 1
+
+        selected_arr = np.array(selected, dtype=np.intp)
+        selected_ranks = all_ranks[selected_arr]
+        selected_cd = np.concatenate(selected_cd_parts).astype(np.float64)
+
+        return selected_arr, {
+            "rank": selected_ranks,
+            "crowding_distance": selected_cd,
+        }
+
+    return selector

ctrl_freak/survival/truncation.py

@@ -0,0 +1,104 @@
+"""Truncation survival selection for single-objective optimization."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ctrl_freak.population import Population
+
+
+def truncation_survival():
+    """Create truncation survivor selector.
+
+    Truncation survival keeps the k best individuals by fitness value.
+    Lower fitness is better (minimization).
+
+    Returns
+    -------
+    callable
+        Survivor selector callable.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from ctrl_freak.population import Population
+    >>> from ctrl_freak.survival.truncation import truncation_survival
+    >>> obj = np.array([[4.0], [2.0], [3.0], [1.0]])
+    >>> pop = Population(x=np.zeros((4, 1)), objectives=obj)
+    >>> indices, state = truncation_survival()(pop, n_survivors=2)
+    >>> indices
+    array([3, 1])
+    >>> state["fitness"].shape
+    (2,)
+    """
+
+    def selector(
+        pop: Population,
+        n_survivors: int,
+        **kwargs: np.ndarray,
+    ) -> tuple[np.ndarray, dict[str, np.ndarray]]:
+        """Select survivors using truncation selection.
+
+        Parameters
+        ----------
+        pop
+            Population to select from.
+        n_survivors
+            Number of survivors to select.
+        **kwargs
+            Optional ``fitness`` array. If omitted, fitness is extracted from a
+            single-objective population.
+
+        Returns
+        -------
+        tuple[numpy.ndarray, dict[str, numpy.ndarray]]
+            Selected indices and state containing the selected ``fitness`` values.
+
+        Raises
+        ------
+        ValueError
+            If inputs are invalid or no valid fitness source is available.
+
+        Examples
+        --------
+        >>> import numpy as np
+        >>> from ctrl_freak.population import Population
+        >>> from ctrl_freak.survival.truncation import truncation_survival
+        >>> obj = np.array([[4.0], [2.0], [3.0], [1.0]])
+        >>> pop = Population(x=np.zeros((4, 1)), objectives=obj)
+        >>> indices, state = truncation_survival()(pop, n_survivors=2)
+        >>> indices
+        array([3, 1])
+        >>> state["fitness"]
+        array([1., 2.])
+        """
+        # Validate n_survivors
+        if n_survivors <= 0:
+            raise ValueError(f"n_survivors must be positive, got {n_survivors}")
+        if n_survivors > len(pop):
+            raise ValueError(f"n_survivors ({n_survivors}) cannot exceed population size ({len(pop)})")
+
+        # Get fitness values
+        fitness = kwargs.get("fitness")
+        if fitness is None:
+            if pop.objectives is None:
+                raise ValueError("Population must have objectives computed for survivor selection")
+            if pop.objectives.shape[1] != 1:
+                raise ValueError(
+                    f"truncation requires single-objective optimization "
+                    f"(got {pop.objectives.shape[1]} objectives). "
+                    "Pass explicit 'fitness' kwarg for multi-objective."
+                )
+            fitness = pop.objectives[:, 0]
+
+        # Sort by fitness (ascending = best first for minimization)
+        # Use stable sort for deterministic tie-breaking
+        sorted_indices = np.argsort(fitness, kind="stable")
+        survivor_indices = sorted_indices[:n_survivors].astype(np.intp)
+
+        # Compute state for survivors
+        survivor_fitness = fitness[survivor_indices].copy()
+
+        return survivor_indices, {"fitness": survivor_fitness}
+
+    return selector