ctrl-freak 0.1.0__py3-none-any.whl

ctrl_freak/registry.py

@@ -0,0 +1,303 @@
+"""Registry system for selection and survival strategies.
+
+This module provides a registry pattern for managing selection and survival
+strategies in evolutionary algorithms. Instead of hardcoding strategy
+implementations, users can register factories that create configured selectors
+and retrieve them by name.
+
+The registry pattern enables:
+- **Pluggable strategies**: Swap selection methods without code changes
+- **Configuration-driven experiments**: Select strategies by string name from config files
+- **Discoverability**: List all available strategies programmatically
+- **Factory pattern**: Register functions that create configured selectors
+
+There are two independent registries:
+1. **SelectionRegistry**: For parent selection strategies (ParentSelector protocol)
+2. **SurvivalRegistry**: For survivor selection strategies (SurvivorSelector protocol)
+
+Examples
+--------
+Strategies are registered as factories and retrieved by name::
+
+    from ctrl_freak.registry import SelectionRegistry, list_selections
+
+    def tournament_factory(size=2):
+        def tournament_selector(pop, n_parents, rng, **kwargs):
+            ...
+        return tournament_selector
+
+    SelectionRegistry.register("tournament", tournament_factory)
+    selector = SelectionRegistry.get("tournament", size=3)
+    available = list_selections()
+"""
+
+from collections.abc import Callable
+
+from ctrl_freak.protocols import ParentSelector, SurvivorSelector
+
+
+class SelectionRegistry:
+    """Registry for parent selection strategies.
+
+    This class provides a class-level registry for parent selection strategy
+    factories. Strategies are registered by name and can be retrieved with
+    custom configuration parameters.
+
+    The registry stores factory functions that accept keyword arguments and
+    return ParentSelector callables. This enables flexible configuration at
+    retrieval time.
+
+    Attributes
+    ----------
+    _registry : dict[str, Callable[..., ParentSelector]]
+        Mapping from strategy names to factory functions.
+
+    Examples
+    --------
+    A strategy factory returns a callable that satisfies ``ParentSelector``::
+
+        def tournament_factory(size=2):
+            def selector(pop, n_parents, rng, **kwargs):
+                ...
+            return selector
+
+        SelectionRegistry.register("tournament", tournament_factory)
+        selector = SelectionRegistry.get("tournament", size=5)
+    """
+
+    _registry: dict[str, Callable[..., ParentSelector]] = {}
+
+    @classmethod
+    def register(cls, name: str, factory: Callable[..., ParentSelector]) -> None:
+        """Register a parent selection strategy factory.
+
+        The factory is a callable that accepts keyword arguments and returns
+        a ParentSelector. This enables strategies to be configured at retrieval
+        time with custom parameters.
+
+        Parameters
+        ----------
+        name : str
+            Unique name for the strategy. Existing names are overwritten.
+        factory : Callable[..., ParentSelector]
+            Callable that returns a parent selector.
+
+        Examples
+        --------
+        >>> from ctrl_freak.registry import SelectionRegistry
+        >>> SelectionRegistry.register(
+        ...     "__doc_random__",
+        ...     lambda: lambda pop, n_parents, rng, **kw: rng.choice(len(pop), n_parents),
+        ... )
+        >>> "__doc_random__" in SelectionRegistry.list()
+        True
+        """
+        cls._registry[name] = factory
+
+    @classmethod
+    def get(cls, name: str, **kwargs) -> ParentSelector:
+        """Get a configured parent selector by name.
+
+        Retrieves the factory for the given strategy name and calls it with
+        the provided keyword arguments to create a configured selector.
+
+        Parameters
+        ----------
+        name : str
+            Name of the registered strategy.
+        **kwargs
+            Configuration parameters passed to the factory function.
+
+        Returns
+        -------
+        ParentSelector
+            A configured parent selector callable.
+
+        Raises
+        ------
+        KeyError
+            If the strategy name is not registered.
+
+        Examples
+        --------
+        >>> from ctrl_freak.registry import SelectionRegistry
+        >>> SelectionRegistry.register("__doc_empty__", lambda: lambda pop, n, rng, **kw: [])
+        >>> selector = SelectionRegistry.get("__doc_empty__")
+        >>> callable(selector)
+        True
+        """
+        if name not in cls._registry:
+            available = ", ".join(sorted(cls._registry.keys())) or "none"
+            raise KeyError(f"Selection strategy '{name}' not found. Available strategies: {available}")
+        factory = cls._registry[name]
+        return factory(**kwargs)
+
+    @classmethod
+    def list(cls) -> list[str]:
+        """Return list of registered strategy names.
+
+        Returns
+        -------
+        list[str]
+            Sorted list of all registered parent selection strategy names.
+
+        Examples
+        --------
+        >>> from ctrl_freak.registry import SelectionRegistry
+        >>> isinstance(SelectionRegistry.list(), list)
+        True
+        """
+        return sorted(cls._registry.keys())
+
+
+class SurvivalRegistry:
+    """Registry for survivor selection strategies.
+
+    This class provides a class-level registry for survivor selection strategy
+    factories. Strategies are registered by name and can be retrieved with
+    custom configuration parameters.
+
+    The registry stores factory functions that accept keyword arguments and
+    return SurvivorSelector callables. This enables flexible configuration at
+    retrieval time.
+
+    Attributes
+    ----------
+    _registry : dict[str, Callable[..., SurvivorSelector]]
+        Mapping from strategy names to factory functions.
+
+    Examples
+    --------
+    A strategy factory returns a callable that satisfies ``SurvivorSelector``::
+
+        def nsga2_factory(preserve_diversity=True):
+            def selector(pop, n_survivors, **kwargs):
+                ...
+            return selector
+
+        SurvivalRegistry.register("nsga2", nsga2_factory)
+        selector = SurvivalRegistry.get("nsga2", preserve_diversity=False)
+    """
+
+    _registry: dict[str, Callable[..., SurvivorSelector]] = {}
+
+    @classmethod
+    def register(cls, name: str, factory: Callable[..., SurvivorSelector]) -> None:
+        """Register a survivor selection strategy factory.
+
+        The factory is a callable that accepts keyword arguments and returns
+        a SurvivorSelector. This enables strategies to be configured at retrieval
+        time with custom parameters.
+
+        Parameters
+        ----------
+        name : str
+            Unique name for the strategy. Existing names are overwritten.
+        factory : Callable[..., SurvivorSelector]
+            Callable that returns a survivor selector.
+
+        Examples
+        --------
+        >>> import numpy as np
+        >>> from ctrl_freak.registry import SurvivalRegistry
+        >>> SurvivalRegistry.register(
+        ...     "__doc_truncation__",
+        ...     lambda: lambda pop, n, **kw: (np.arange(n), {}),
+        ... )
+        >>> "__doc_truncation__" in SurvivalRegistry.list()
+        True
+        """
+        cls._registry[name] = factory
+
+    @classmethod
+    def get(cls, name: str, **kwargs) -> SurvivorSelector:
+        """Get a configured survivor selector by name.
+
+        Retrieves the factory for the given strategy name and calls it with
+        the provided keyword arguments to create a configured selector.
+
+        Parameters
+        ----------
+        name : str
+            Name of the registered strategy.
+        **kwargs
+            Configuration parameters passed to the factory function.
+
+        Returns
+        -------
+        SurvivorSelector
+            A configured survivor selector callable.
+
+        Raises
+        ------
+        KeyError
+            If the strategy name is not registered.
+
+        Examples
+        --------
+        >>> from ctrl_freak.registry import SurvivalRegistry
+        >>> SurvivalRegistry.register("__doc_survivor__", lambda: lambda pop, n, **kw: ([], {}))
+        >>> selector = SurvivalRegistry.get("__doc_survivor__")
+        >>> callable(selector)
+        True
+        """
+        if name not in cls._registry:
+            available = ", ".join(sorted(cls._registry.keys())) or "none"
+            raise KeyError(f"Survival strategy '{name}' not found. Available strategies: {available}")
+        factory = cls._registry[name]
+        return factory(**kwargs)
+
+    @classmethod
+    def list(cls) -> list[str]:
+        """Return list of registered strategy names.
+
+        Returns
+        -------
+        list[str]
+            Sorted list of all registered survivor selection strategy names.
+
+        Examples
+        --------
+        >>> from ctrl_freak.registry import SurvivalRegistry
+        >>> isinstance(SurvivalRegistry.list(), list)
+        True
+        """
+        return sorted(cls._registry.keys())
+
+
+def list_selections() -> list[str]:
+    """List all registered parent selection strategies.
+
+    Convenience function that returns SelectionRegistry.list().
+
+    Returns
+    -------
+    list[str]
+        Sorted list of all registered parent selection strategy names.
+
+    Examples
+    --------
+    >>> from ctrl_freak.registry import list_selections
+    >>> isinstance(list_selections(), list)
+    True
+    """
+    return SelectionRegistry.list()
+
+
+def list_survivals() -> list[str]:
+    """List all registered survivor selection strategies.
+
+    Convenience function that returns SurvivalRegistry.list().
+
+    Returns
+    -------
+    list[str]
+        Sorted list of all registered survivor selection strategy names.
+
+    Examples
+    --------
+    >>> from ctrl_freak.registry import list_survivals
+    >>> isinstance(list_survivals(), list)
+    True
+    """
+    return SurvivalRegistry.list()

ctrl_freak/results.py

@@ -0,0 +1,246 @@
+"""Algorithm-specific result types for genetic algorithms.
+
+This module provides result dataclasses that encapsulate algorithm-specific
+metadata along with the final population:
+
+- NSGA2Result: Results from NSGA-II multi-objective optimization
+- GAResult: Results from single-objective genetic algorithms
+
+Both classes are immutable (frozen dataclasses) to enforce functional style.
+All numpy arrays are copied on construction to ensure immutability.
+"""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from ctrl_freak.population import Population
+
+
+@dataclass(frozen=True)
+class NSGA2Result:
+    """Results from NSGA-II multi-objective optimization algorithm.
+
+    This class encapsulates the final population along with algorithm-specific
+    metadata like Pareto ranks and crowding distances. All arrays are copied
+    on construction to ensure immutability.
+
+    Attributes
+    ----------
+    population : Population
+        The final population after optimization.
+    rank : numpy.ndarray
+        Pareto rank for each individual. Rank 0 indicates individuals on the
+        Pareto front.
+    crowding_distance : numpy.ndarray
+        Crowding distance for each individual.
+    generations : int
+        Number of generations completed during optimization.
+    evaluations : int
+        Total number of objective function evaluations performed.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from ctrl_freak.population import Population
+    >>> from ctrl_freak.results import NSGA2Result
+    >>> x = np.array([[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]])
+    >>> obj = np.array([[0.5, 0.5], [0.3, 0.7], [0.4, 0.6]])
+    >>> pop = Population(x=x, objectives=obj)
+    >>> result = NSGA2Result(
+    ...     population=pop,
+    ...     rank=np.array([0, 0, 1]),
+    ...     crowding_distance=np.array([np.inf, np.inf, 0.5]),
+    ...     generations=100,
+    ...     evaluations=5000,
+    ... )
+    >>> len(result.pareto_front)
+    2
+    """
+
+    population: Population
+    rank: np.ndarray
+    crowding_distance: np.ndarray
+    generations: int
+    evaluations: int
+
+    def __post_init__(self) -> None:
+        """Validate shapes and copy arrays for immutability.
+
+        Raises
+        ------
+        TypeError
+            If rank or crowding_distance are not numpy arrays.
+        ValueError
+            If array shapes are inconsistent.
+        """
+        n = len(self.population)
+
+        # Validate rank
+        if not isinstance(self.rank, np.ndarray):
+            raise TypeError(f"rank must be a numpy array, got {type(self.rank).__name__}")
+        if self.rank.ndim != 1:
+            raise ValueError(f"rank must be 1D, got shape {self.rank.shape}")
+        if self.rank.shape[0] != n:
+            raise ValueError(f"rank has {self.rank.shape[0]} elements, expected {n} to match population size")
+
+        # Validate crowding_distance
+        if not isinstance(self.crowding_distance, np.ndarray):
+            raise TypeError(f"crowding_distance must be a numpy array, got {type(self.crowding_distance).__name__}")
+        if self.crowding_distance.ndim != 1:
+            raise ValueError(f"crowding_distance must be 1D, got shape {self.crowding_distance.shape}")
+        if self.crowding_distance.shape[0] != n:
+            raise ValueError(
+                f"crowding_distance has {self.crowding_distance.shape[0]} elements, expected {n} to match population size"
+            )
+
+        # Copy arrays for immutability (use object.__setattr__ for frozen dataclass)
+        object.__setattr__(self, "rank", self.rank.copy())
+        object.__setattr__(self, "crowding_distance", self.crowding_distance.copy())
+
+    @property
+    def pareto_front(self) -> Population:
+        """Extract the Pareto front (rank-0 individuals) as a new Population.
+
+        Returns
+        -------
+        Population
+            A new Population containing only individuals with rank 0.
+
+        Examples
+        --------
+        >>> import numpy as np
+        >>> from ctrl_freak.population import Population
+        >>> from ctrl_freak.results import NSGA2Result
+        >>> pop = Population(
+        ...     x=np.array([[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]]),
+        ...     objectives=np.array([[0.5, 0.5], [0.3, 0.7], [0.4, 0.6]]),
+        ... )
+        >>> result = NSGA2Result(
+        ...     population=pop,
+        ...     rank=np.array([0, 0, 1]),
+        ...     crowding_distance=np.array([np.inf, np.inf, 0.5]),
+        ...     generations=1,
+        ...     evaluations=3,
+        ... )
+        >>> len(result.pareto_front)
+        2
+        """
+        # Find indices of rank-0 individuals
+        rank_0_mask = self.rank == 0
+        rank_0_indices = np.where(rank_0_mask)[0]
+
+        # Extract rank-0 individuals
+        x_front = self.population.x[rank_0_indices]
+        objectives_front = (
+            self.population.objectives[rank_0_indices] if self.population.objectives is not None else None
+        )
+
+        return Population(x=x_front, objectives=objectives_front)
+
+
+@dataclass(frozen=True)
+class GAResult:
+    """Results from single-objective genetic algorithm optimization.
+
+    This class encapsulates the final population along with fitness values
+    for each individual. In minimization problems, lower fitness is better.
+    All arrays are copied on construction to ensure immutability.
+
+    Attributes
+    ----------
+    population : Population
+        The final population after optimization.
+    fitness : numpy.ndarray
+        Fitness values for each individual. Lower values indicate better
+        fitness for minimization problems.
+    best_idx : int
+        Index of the best individual.
+    generations : int
+        Number of generations completed during optimization.
+    evaluations : int
+        Total number of objective function evaluations performed.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from ctrl_freak.population import Population
+    >>> from ctrl_freak.results import GAResult
+    >>> pop = Population(x=np.array([[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]]))
+    >>> result = GAResult(
+    ...     population=pop,
+    ...     fitness=np.array([0.5, 0.3, 0.7]),
+    ...     best_idx=1,
+    ...     generations=50,
+    ...     evaluations=2500,
+    ... )
+    >>> result.best[1]
+    0.3
+    """
+
+    population: Population
+    fitness: np.ndarray
+    best_idx: int
+    generations: int
+    evaluations: int
+
+    def __post_init__(self) -> None:
+        """Validate shapes and copy arrays for immutability.
+
+        Raises
+        ------
+        TypeError
+            If fitness is not a numpy array or best_idx is not an integer.
+        ValueError
+            If array shapes are inconsistent or best_idx is out of bounds.
+        """
+        n = len(self.population)
+
+        # Validate fitness
+        if not isinstance(self.fitness, np.ndarray):
+            raise TypeError(f"fitness must be a numpy array, got {type(self.fitness).__name__}")
+        if self.fitness.ndim != 1:
+            raise ValueError(f"fitness must be 1D, got shape {self.fitness.shape}")
+        if self.fitness.shape[0] != n:
+            raise ValueError(f"fitness has {self.fitness.shape[0]} elements, expected {n} to match population size")
+
+        # Validate best_idx
+        if not isinstance(self.best_idx, (int, np.integer)):
+            raise TypeError(f"best_idx must be an integer, got {type(self.best_idx).__name__}")
+        if self.best_idx < 0 or self.best_idx >= n:
+            raise ValueError(f"best_idx {self.best_idx} is out of bounds for population with {n} individuals")
+
+        # Copy fitness for immutability (use object.__setattr__ for frozen dataclass)
+        object.__setattr__(self, "fitness", self.fitness.copy())
+
+    @property
+    def best(self) -> tuple[np.ndarray, float]:
+        """Extract the best individual and its fitness value.
+
+        Returns
+        -------
+        tuple[numpy.ndarray, float]
+            Decision variables and fitness value for the best individual.
+
+        Examples
+        --------
+        >>> import numpy as np
+        >>> from ctrl_freak.population import Population
+        >>> from ctrl_freak.results import GAResult
+        >>> pop = Population(x=np.array([[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]]))
+        >>> result = GAResult(
+        ...     population=pop,
+        ...     fitness=np.array([0.5, 0.3, 0.7]),
+        ...     best_idx=1,
+        ...     generations=1,
+        ...     evaluations=3,
+        ... )
+        >>> best_x, best_fitness = result.best
+        >>> best_x
+        array([3., 4.])
+        >>> best_fitness
+        0.3
+        """
+        best_x = self.population.x[self.best_idx]
+        best_fitness = self.fitness[self.best_idx]
+        return (best_x, float(best_fitness))

ctrl_freak/selection/__init__.py

@@ -0,0 +1,13 @@
+"""Selection strategies for genetic algorithms."""
+
+from ctrl_freak.registry import SelectionRegistry
+from ctrl_freak.selection.crowded import crowded_tournament
+from ctrl_freak.selection.roulette import roulette_wheel
+from ctrl_freak.selection.tournament import fitness_tournament
+
+# Register built-in selection strategies
+SelectionRegistry.register("crowded", crowded_tournament)
+SelectionRegistry.register("tournament", fitness_tournament)
+SelectionRegistry.register("roulette", roulette_wheel)
+
+__all__ = ["crowded_tournament", "fitness_tournament", "roulette_wheel"]

ctrl_freak/selection/crowded.py

@@ -0,0 +1,117 @@
+"""Crowded tournament selection for multi-objective optimization."""
+
+import numpy as np
+
+from ctrl_freak.population import Population
+
+
+def crowded_tournament(tournament_size: int = 2):
+    """Create a crowded tournament parent selector.
+
+    In crowded tournament selection, individuals are compared by:
+    1. Pareto rank (lower is better)
+    2. If ranks are equal, crowding distance (higher is better for diversity)
+
+    Parameters
+    ----------
+    tournament_size
+        Number of individuals 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.crowded import crowded_tournament
+    >>> pop = Population(x=np.zeros((4, 2)), objectives=np.zeros((4, 2)))
+    >>> rng = np.random.default_rng(0)
+    >>> rank = np.array([0, 0, 1, 1])
+    >>> cd = np.array([1.0, 2.0, 1.0, 2.0])
+    >>> selector = crowded_tournament(tournament_size=2)
+    >>> parents = selector(pop, 6, rng, rank=rank, crowding_distance=cd)
+    >>> parents.shape
+    (6,)
+    """
+
+    def selector(
+        pop: Population,
+        n_parents: int,
+        rng: np.random.Generator,
+        **kwargs: np.ndarray,
+    ) -> np.ndarray:
+        """Select parents using crowded tournament selection.
+
+        Parameters
+        ----------
+        pop
+            Population to select from.
+        n_parents
+            Number of parents to select.
+        rng
+            Random number generator.
+        **kwargs
+            Must include ``rank`` and ``crowding_distance`` arrays.
+
+        Returns
+        -------
+        numpy.ndarray
+            Selected parent indices.
+
+        Raises
+        ------
+        ValueError
+            If ``rank`` or ``crowding_distance`` is missing.
+
+        Examples
+        --------
+        >>> import numpy as np
+        >>> from ctrl_freak.population import Population
+        >>> from ctrl_freak.selection.crowded import crowded_tournament
+        >>> pop = Population(x=np.zeros((4, 1)), objectives=np.zeros((4, 2)))
+        >>> selector = crowded_tournament()
+        >>> out = selector(
+        ...     pop,
+        ...     3,
+        ...     np.random.default_rng(1),
+        ...     rank=np.array([0, 1, 0, 1]),
+        ...     crowding_distance=np.ones(4),
+        ... )
+        >>> out.shape
+        (3,)
+        """
+        # Validate required kwargs
+        if "rank" not in kwargs:
+            raise ValueError("crowded tournament selection requires 'rank' in kwargs")
+        if "crowding_distance" not in kwargs:
+            raise ValueError("crowded tournament selection requires 'crowding_distance' in kwargs")
+
+        rank = kwargs["rank"]
+        crowding_distance = kwargs["crowding_distance"]
+        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 rank, break ties with higher crowding distance
+            best_idx = candidates[0]
+            for c in candidates[1:]:
+                if (
+                    rank[c] < rank[best_idx]
+                    or rank[c] == rank[best_idx]
+                    and crowding_distance[c] > crowding_distance[best_idx]
+                ):
+                    best_idx = c
+
+            selected[i] = best_idx
+
+        return selected
+
+    return selector