ctrl-freak 0.1.0__py3-none-any.whl

ctrl_freak/__init__.py

@@ -0,0 +1,100 @@
+"""ctrl-freak: Extensible Genetic Algorithm Framework.
+
+A pure numpy implementation of genetic algorithms including NSGA-II for
+multi-objective optimization and standard GA for single-objective optimization.
+
+Example (multi-objective with NSGA-II):
+    >>> from ctrl_freak import nsga2, Population
+    >>> import numpy as np
+    >>> def init(rng): return rng.uniform(0, 1, size=3)
+    >>> def evaluate(x): return np.array([x.sum(), (1 - x).sum()])
+    >>> def crossover(p1, p2): return (p1 + p2) / 2
+    >>> def mutate(x): return np.clip(x + 0.01, 0, 1)
+    >>> result = nsga2(init, evaluate, crossover, mutate, pop_size=10, n_generations=5, seed=42)
+    >>> len(result.population)
+    10
+
+Example (single-objective with GA):
+    >>> from ctrl_freak import ga
+    >>> import numpy as np
+    >>> def init(rng): return rng.uniform(0, 1, size=3)
+    >>> def evaluate(x): return x.sum()  # Single objective
+    >>> def crossover(p1, p2): return (p1 + p2) / 2
+    >>> def mutate(x): return np.clip(x + 0.01, 0, 1)
+    >>> result = ga(init, evaluate, crossover, mutate, pop_size=10, n_generations=5, seed=42)
+    >>> len(result.population)
+    10
+"""
+
+from importlib.metadata import version
+
+from ctrl_freak.algorithms import ga, nsga2
+from ctrl_freak.operators import (
+    create_offspring,
+    lift,
+    lift_parallel,
+    polynomial_mutation,
+    sbx_crossover,
+    select_parents,
+)
+from ctrl_freak.population import IndividualView, Population
+from ctrl_freak.primitives import (
+    crowding_distance,
+    dominates,
+    dominates_matrix,
+    non_dominated_sort,
+)
+from ctrl_freak.protocols import ParentSelector, SurvivorSelector
+from ctrl_freak.registry import (
+    SelectionRegistry,
+    SurvivalRegistry,
+    list_selections,
+    list_survivals,
+)
+from ctrl_freak.results import GAResult, NSGA2Result
+from ctrl_freak.selection import crowded_tournament, fitness_tournament, roulette_wheel
+from ctrl_freak.survival import elitist_survival, nsga2_survival, truncation_survival
+
+__version__ = version("ctrl-freak")
+
+__all__ = [
+    # Algorithms
+    "nsga2",
+    "ga",
+    # Selection strategies
+    "crowded_tournament",
+    "fitness_tournament",
+    "roulette_wheel",
+    # Survival strategies
+    "nsga2_survival",
+    "truncation_survival",
+    "elitist_survival",
+    # Genetic operators
+    "lift",
+    "lift_parallel",
+    "select_parents",
+    "create_offspring",
+    "sbx_crossover",
+    "polynomial_mutation",
+    # Primitives
+    "dominates",
+    "dominates_matrix",
+    "non_dominated_sort",
+    "crowding_distance",
+    # Registry system
+    "SelectionRegistry",
+    "SurvivalRegistry",
+    "list_selections",
+    "list_survivals",
+    # Protocols
+    "ParentSelector",
+    "SurvivorSelector",
+    # Data structures
+    "Population",
+    "IndividualView",
+    # Result types
+    "NSGA2Result",
+    "GAResult",
+    # Version
+    "__version__",
+]

ctrl_freak/algorithms/__init__.py

@@ -0,0 +1,10 @@
+"""Evolutionary algorithm implementations.
+
+This module provides pluggable algorithm implementations with configurable
+selection and survival strategies.
+"""
+
+from ctrl_freak.algorithms.ga import ga
+from ctrl_freak.algorithms.nsga2 import nsga2
+
+__all__ = ["ga", "nsga2"]

ctrl_freak/algorithms/ga.py

@@ -0,0 +1,233 @@
+"""Standard genetic algorithm with pluggable strategies.
+
+Examples
+--------
+>>> import numpy as np
+>>> from ctrl_freak.algorithms.ga import ga
+>>> def init(rng):
+...     return rng.uniform(0.0, 1.0, size=3)
+>>> def evaluate(x):
+...     return float(np.sum(x**2))
+>>> result = ga(
+...     init=init,
+...     evaluate=evaluate,
+...     crossover=lambda p1, p2: (p1 + p2) / 2,
+...     mutate=lambda x: np.clip(x + 0.01, 0.0, 1.0),
+...     pop_size=10,
+...     n_generations=2,
+...     seed=42,
+... )
+>>> result.population.x.shape
+(10, 3)
+"""
+
+from collections.abc import Callable
+
+import numpy as np
+
+# Import selection and survival modules to trigger strategy registration
+import ctrl_freak.selection  # noqa: F401
+import ctrl_freak.survival  # noqa: F401
+from ctrl_freak.operators import lift, lift_parallel
+from ctrl_freak.population import Population
+from ctrl_freak.protocols import ParentSelector, SurvivorSelector
+from ctrl_freak.registry import SelectionRegistry, SurvivalRegistry
+from ctrl_freak.results import GAResult
+
+
+def ga(
+    init: Callable[[np.random.Generator], np.ndarray],
+    evaluate: Callable[[np.ndarray], float],
+    crossover: Callable[[np.ndarray, np.ndarray], np.ndarray],
+    mutate: Callable[[np.ndarray], np.ndarray],
+    pop_size: int,
+    n_generations: int,
+    seed: int | None = None,
+    callback: Callable[[GAResult, int], bool] | None = None,
+    select: str | ParentSelector = "tournament",
+    survive: str | SurvivorSelector = "elitist",
+    n_workers: int = 1,
+) -> GAResult:
+    """Run a single-objective genetic algorithm.
+
+    Parameters
+    ----------
+    init
+        Callable that initializes one individual from a random generator.
+    evaluate
+        Callable that evaluates one individual and returns a scalar objective.
+        Lower objective values are better.
+    crossover
+        Callable that crosses two parents to produce one child.
+    mutate
+        Callable that mutates one individual.
+    pop_size
+        Population size. Must be positive and even.
+    n_generations
+        Number of generations to run.
+    seed
+        Master random seed. If ``None``, system entropy is used.
+    callback
+        Optional callback called before each generation. Return ``True`` to stop.
+    select
+        Parent selection strategy name or callable.
+    survive
+        Survivor selection strategy name or callable.
+    n_workers
+        Number of workers for objective evaluation. Parallel evaluation is
+        deterministic only when ``evaluate`` is pure.
+
+    Returns
+    -------
+    GAResult
+        Final population, fitness vector, best index, generation count, and
+        evaluation count.
+
+    Raises
+    ------
+    ValueError
+        If size, generation, or worker arguments are invalid.
+    KeyError
+        If a named strategy is not registered.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from ctrl_freak.algorithms.ga import ga
+    >>> def init(rng):
+    ...     return rng.uniform(0.0, 1.0, size=2)
+    >>> def evaluate(x):
+    ...     return float(np.sum(x**2))
+    >>> result = ga(
+    ...     init=init,
+    ...     evaluate=evaluate,
+    ...     crossover=lambda p1, p2: (p1 + p2) / 2,
+    ...     mutate=lambda x: x.copy(),
+    ...     pop_size=10,
+    ...     n_generations=2,
+    ...     seed=1,
+    ... )
+    >>> result.generations
+    2
+    """
+    # Validate inputs
+    if pop_size <= 0:
+        raise ValueError(f"pop_size must be positive, got {pop_size}")
+    if pop_size % 2 != 0:
+        raise ValueError(f"pop_size must be even for proper parent pairing, got {pop_size}")
+    if n_generations < 0:
+        raise ValueError(f"n_generations must be non-negative, got {n_generations}")
+    if n_workers < 1 and n_workers != -1:
+        raise ValueError(f"n_workers must be positive or -1 (all cores), got {n_workers}")
+
+    # Resolve selection and survival strategies
+    parent_selector = SelectionRegistry.get(select) if isinstance(select, str) else select
+    survivor_selector = SurvivalRegistry.get(survive) if isinstance(survive, str) else survive
+
+    # Derive independent per-phase RNG streams from the single master seed so one seed
+    # reproduces init + parent selection + crossover + mutation bit-identically.
+    # Child order is the reproducibility contract: [init, select, crossover, mutate]. Never reorder.
+    init_ss, select_ss, crossover_ss, mutate_ss = np.random.SeedSequence(seed).spawn(4)
+    rng = np.random.default_rng(init_ss)
+    select_rng = np.random.default_rng(select_ss)
+    set_crossover_rng = getattr(crossover, "set_rng", None)
+    if callable(set_crossover_rng):
+        set_crossover_rng(np.random.default_rng(crossover_ss))
+    set_mutate_rng = getattr(mutate, "set_rng", None)
+    if callable(set_mutate_rng):
+        set_mutate_rng(np.random.default_rng(mutate_ss))
+
+    def evaluate_array(x: np.ndarray) -> np.ndarray:
+        return np.asarray(evaluate(x))
+
+    # Shared lifted evaluation path. Parallel determinism assumes evaluate is pure.
+    lifted_evaluate = lift_parallel(evaluate_array, n_workers) if n_workers != 1 else lift(evaluate_array)
+
+    # Initialize population
+    init_x = np.stack([init(rng) for _ in range(pop_size)])
+    init_obj = lifted_evaluate(init_x)
+    if init_obj.ndim == 1:
+        init_obj = init_obj.reshape(-1, 1)
+
+    pop = Population(x=init_x, objectives=init_obj)
+
+    # Compute initial fitness state
+    # Extract fitness from single-objective population
+    assert pop.objectives is not None  # Guaranteed by initialization above
+    state: dict[str, np.ndarray] = {"fitness": pop.objectives[:, 0].copy()}
+
+    # Track evaluations: initial population
+    total_evaluations = pop_size
+    generations_completed = 0
+
+    # Main evolutionary loop
+    for gen in range(n_generations):
+        # Extract fitness from state for current GAResult
+        fitness = state["fitness"]
+        best_idx = int(np.argmin(fitness))
+
+        # Create current GAResult for callback
+        current_result = GAResult(
+            population=pop,
+            fitness=fitness,
+            best_idx=best_idx,
+            generations=generations_completed,
+            evaluations=total_evaluations,
+        )
+
+        # Check callback for early stopping
+        if callback is not None and callback(current_result, gen):
+            break
+
+        # Select parents using current state
+        parent_indices = parent_selector(pop, pop_size, select_rng, **state)
+
+        # Create offspring via crossover and mutation
+        offspring_x = np.empty_like(pop.x)
+        for i in range(0, pop_size, 2):
+            p1_idx, p2_idx = parent_indices[i], parent_indices[i + 1]
+            child1 = crossover(pop.x[p1_idx], pop.x[p2_idx])
+            child2 = crossover(pop.x[p2_idx], pop.x[p1_idx])
+            offspring_x[i] = mutate(child1)
+            offspring_x[i + 1] = mutate(child2)
+
+        offspring_obj = lifted_evaluate(offspring_x)
+        if offspring_obj.ndim == 1:
+            offspring_obj = offspring_obj.reshape(-1, 1)
+        total_evaluations += pop_size
+
+        # Combine parent and offspring populations
+        assert pop.objectives is not None  # Guaranteed by initialization
+        combined = Population(
+            x=np.concatenate([pop.x, offspring_x]),
+            objectives=np.concatenate([pop.objectives, offspring_obj]),
+        )
+
+        survivor_indices, state = survivor_selector(
+            combined,
+            pop_size,
+            parent_size=pop_size,
+        )
+
+        # Update population
+        assert combined.objectives is not None  # Guaranteed by Population construction above
+        pop = Population(
+            x=combined.x[survivor_indices],
+            objectives=combined.objectives[survivor_indices],
+        )
+
+        generations_completed += 1
+
+    # Return final result
+    fitness = state["fitness"]
+    best_idx = int(np.argmin(fitness))
+
+    final_result = GAResult(
+        population=pop,
+        fitness=fitness,
+        best_idx=best_idx,
+        generations=generations_completed,
+        evaluations=total_evaluations,
+    )
+
+    return final_result

ctrl_freak/algorithms/nsga2.py

@@ -0,0 +1,215 @@
+"""NSGA-II algorithm with pluggable strategies.
+
+Examples
+--------
+>>> import numpy as np
+>>> from ctrl_freak.algorithms.nsga2 import nsga2
+>>> def init(rng):
+...     return rng.uniform(0.0, 1.0, size=3)
+>>> def evaluate(x):
+...     return np.array([np.sum(x), np.sum(1.0 - x)])
+>>> result = nsga2(
+...     init=init,
+...     evaluate=evaluate,
+...     crossover=lambda p1, p2: (p1 + p2) / 2,
+...     mutate=lambda x: np.clip(x + 0.01, 0.0, 1.0),
+...     pop_size=10,
+...     n_generations=2,
+...     seed=42,
+... )
+>>> result.population.x.shape
+(10, 3)
+"""
+
+from collections.abc import Callable
+
+import numpy as np
+
+# Import selection and survival modules to trigger strategy registration
+import ctrl_freak.selection  # noqa: F401
+import ctrl_freak.survival  # noqa: F401
+from ctrl_freak.operators import lift, lift_parallel
+from ctrl_freak.population import Population
+from ctrl_freak.protocols import ParentSelector, SurvivorSelector
+from ctrl_freak.registry import SelectionRegistry, SurvivalRegistry
+from ctrl_freak.results import NSGA2Result
+
+
+def nsga2(
+    init: Callable[[np.random.Generator], np.ndarray],
+    evaluate: Callable[[np.ndarray], np.ndarray],
+    crossover: Callable[[np.ndarray, np.ndarray], np.ndarray],
+    mutate: Callable[[np.ndarray], np.ndarray],
+    pop_size: int,
+    n_generations: int,
+    seed: int | None = None,
+    callback: Callable[[NSGA2Result, int], bool] | None = None,
+    select: str | ParentSelector = "crowded",
+    survive: str | SurvivorSelector = "nsga2",
+    n_workers: int = 1,
+) -> NSGA2Result:
+    """Run NSGA-II multi-objective optimization.
+
+    Parameters
+    ----------
+    init
+        Callable that initializes one individual from a random generator.
+    evaluate
+        Callable that evaluates one individual and returns objective values.
+    crossover
+        Callable that crosses two parents to produce one child.
+    mutate
+        Callable that mutates one individual.
+    pop_size
+        Population size. Must be positive and even.
+    n_generations
+        Number of generations to run.
+    seed
+        Master random seed. If ``None``, system entropy is used.
+    callback
+        Optional callback called before each generation. Return ``True`` to stop.
+    select
+        Parent selection strategy name or callable.
+    survive
+        Survivor selection strategy name or callable.
+    n_workers
+        Number of workers for objective evaluation. Parallel evaluation is
+        deterministic only when ``evaluate`` is pure.
+
+    Returns
+    -------
+    NSGA2Result
+        Final population, ranks, crowding distances, generation count, and
+        evaluation count.
+
+    Raises
+    ------
+    ValueError
+        If size, generation, or worker arguments are invalid.
+    KeyError
+        If a named strategy is not registered.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from ctrl_freak.algorithms.nsga2 import nsga2
+    >>> def init(rng):
+    ...     return rng.uniform(0.0, 1.0, size=2)
+    >>> def evaluate(x):
+    ...     return np.array([np.sum(x), np.sum(1.0 - x)])
+    >>> result = nsga2(
+    ...     init=init,
+    ...     evaluate=evaluate,
+    ...     crossover=lambda p1, p2: (p1 + p2) / 2,
+    ...     mutate=lambda x: x.copy(),
+    ...     pop_size=10,
+    ...     n_generations=2,
+    ...     seed=1,
+    ... )
+    >>> result.generations
+    2
+    """
+    # Validate inputs
+    if pop_size <= 0:
+        raise ValueError(f"pop_size must be positive, got {pop_size}")
+    if pop_size % 2 != 0:
+        raise ValueError(f"pop_size must be even for proper parent pairing, got {pop_size}")
+    if n_generations < 0:
+        raise ValueError(f"n_generations must be non-negative, got {n_generations}")
+    if n_workers < 1 and n_workers != -1:
+        raise ValueError(f"n_workers must be positive or -1 (all cores), got {n_workers}")
+
+    # Resolve selection and survival strategies
+    parent_selector = SelectionRegistry.get(select) if isinstance(select, str) else select
+
+    survivor_selector = SurvivalRegistry.get(survive) if isinstance(survive, str) else survive
+
+    # Create evaluator (parallel or sequential)
+    lifted_evaluate = lift_parallel(evaluate, n_workers) if n_workers != 1 else lift(evaluate)
+
+    # Derive independent per-phase RNG streams from the single master seed so one seed
+    # reproduces init + parent selection + crossover + mutation bit-identically.
+    # Child order is the reproducibility contract: [init, select, crossover, mutate]. Never reorder.
+    init_ss, select_ss, crossover_ss, mutate_ss = np.random.SeedSequence(seed).spawn(4)
+    rng = np.random.default_rng(init_ss)
+    select_rng = np.random.default_rng(select_ss)
+    set_crossover_rng = getattr(crossover, "set_rng", None)
+    if callable(set_crossover_rng):
+        set_crossover_rng(np.random.default_rng(crossover_ss))
+    set_mutate_rng = getattr(mutate, "set_rng", None)
+    if callable(set_mutate_rng):
+        set_mutate_rng(np.random.default_rng(mutate_ss))
+
+    # Initialize population
+    init_x = np.stack([init(rng) for _ in range(pop_size)])
+    init_obj = lifted_evaluate(init_x)
+    pop = Population(x=init_x, objectives=init_obj)
+
+    # Compute initial state via survival strategy
+    # This gives us initial rank and crowding distance
+    _, state = survivor_selector(pop, pop_size)
+
+    # Track evaluations: initial population
+    total_evaluations = pop_size
+    generations_completed = 0
+
+    # Main evolutionary loop
+    for gen in range(n_generations):
+        # Create current NSGA2Result for callback
+        current_result = NSGA2Result(
+            population=pop,
+            rank=state["rank"],
+            crowding_distance=state["crowding_distance"],
+            generations=generations_completed,
+            evaluations=total_evaluations,
+        )
+
+        # Check callback for early stopping
+        if callback is not None and callback(current_result, gen):
+            break
+
+        # Select parents using current state
+        parent_indices = parent_selector(pop, pop_size, select_rng, **state)
+
+        # Create offspring via crossover and mutation
+        offspring_x = np.empty_like(pop.x)
+        for i in range(0, pop_size, 2):
+            p1_idx, p2_idx = parent_indices[i], parent_indices[i + 1]
+            child1 = crossover(pop.x[p1_idx], pop.x[p2_idx])
+            child2 = crossover(pop.x[p2_idx], pop.x[p1_idx])
+            offspring_x[i] = mutate(child1)
+            offspring_x[i + 1] = mutate(child2)
+
+        # Evaluate offspring
+        offspring_obj = lifted_evaluate(offspring_x)
+        total_evaluations += pop_size
+
+        # Combine parent and offspring populations
+        assert pop.objectives is not None  # Guaranteed by initialization
+        combined = Population(
+            x=np.concatenate([pop.x, offspring_x]),
+            objectives=np.concatenate([pop.objectives, offspring_obj]),
+        )
+
+        # Select survivors for next generation
+        survivor_indices, state = survivor_selector(combined, pop_size)
+
+        # Update population
+        assert combined.objectives is not None  # Guaranteed by Population construction above
+        pop = Population(
+            x=combined.x[survivor_indices],
+            objectives=combined.objectives[survivor_indices],
+        )
+
+        generations_completed += 1
+
+    # Return final result
+    final_result = NSGA2Result(
+        population=pop,
+        rank=state["rank"],
+        crowding_distance=state["crowding_distance"],
+        generations=generations_completed,
+        evaluations=total_evaluations,
+    )
+
+    return final_result

ctrl_freak/operators/__init__.py

@@ -0,0 +1,15 @@
+"""Genetic operators for evolutionary algorithms.
+
+This module provides:
+- lift: decorator to lift per-individual functions to population level
+- sbx_crossover: Simulated Binary Crossover factory
+- polynomial_mutation: Polynomial mutation factory
+- select_parents: Binary tournament selection
+- create_offspring: Create offspring via selection, crossover, and mutation
+"""
+
+from ctrl_freak.operators.base import lift, lift_parallel
+from ctrl_freak.operators.selection import create_offspring, select_parents
+from ctrl_freak.operators.standard import polynomial_mutation, sbx_crossover
+
+__all__ = ["lift", "lift_parallel", "sbx_crossover", "polynomial_mutation", "select_parents", "create_offspring"]

ctrl_freak/operators/base.py

@@ -0,0 +1,81 @@
+"""Base genetic-operator adapters."""
+
+from collections.abc import Callable
+
+import numpy as np
+
+
+def lift(fn: Callable[[np.ndarray], np.ndarray]) -> Callable[[np.ndarray], np.ndarray]:
+    """Lift a per-individual function to work on a population.
+
+    This utility allows users to write simple per-individual functions
+    while the framework handles batching/vectorization.
+
+    Parameters
+    ----------
+    fn : collections.abc.Callable
+        Function that operates on one individual with signature
+        ``(n_vars,) -> (n_out,)``.
+
+    Returns
+    -------
+    collections.abc.Callable
+        Function that operates on a population with signature
+        ``(n, n_vars) -> (n, n_out)``.
+
+    Examples
+    --------
+    >>> def evaluate_one(x: np.ndarray) -> np.ndarray:
+    ...     return np.array([x.sum(), x.prod()])
+    >>> evaluate = lift(evaluate_one)
+    >>> pop_x = np.array([[1.0, 2.0], [3.0, 4.0]])
+    >>> evaluate(pop_x)
+    array([[ 3.,  2.],
+           [ 7., 12.]])
+    """
+
+    def lifted(x: np.ndarray) -> np.ndarray:
+        return np.stack([fn(x[i]) for i in range(x.shape[0])])
+
+    return lifted
+
+
+def lift_parallel(fn: Callable[[np.ndarray], np.ndarray], n_workers: int) -> Callable[[np.ndarray], np.ndarray]:
+    """Lift a per-individual function to work on a population with parallel execution.
+
+    This utility allows users to write simple per-individual functions
+    while the framework handles batching/vectorization with parallel workers.
+
+    Parameters
+    ----------
+    fn : collections.abc.Callable
+        Function that operates on one individual with signature
+        ``(n_vars,) -> (n_out,)``. It must be picklable for multiprocessing.
+    n_workers : int
+        Number of parallel workers. Use ``-1`` for all CPU cores.
+
+    Returns
+    -------
+    collections.abc.Callable
+        Function that operates on a population in parallel with signature
+        ``(n, n_vars) -> (n, n_out)``.
+
+    Examples
+    --------
+    >>> def evaluate_one(x: np.ndarray) -> np.ndarray:
+    ...     return np.array([x.sum(), x.prod()])
+    >>> evaluate = lift_parallel(evaluate_one, n_workers=4)
+    >>> pop_x = np.array([[1.0, 2.0], [3.0, 4.0]])
+    >>> evaluate(pop_x)
+    array([[ 3.,  2.],
+           [ 7., 12.]])
+    """
+    from joblib import Parallel, delayed
+
+    def lifted(x: np.ndarray) -> np.ndarray:
+        results: list[np.ndarray] = Parallel(n_jobs=n_workers)(  # type: ignore[assignment]
+            delayed(fn)(x[i]) for i in range(x.shape[0])
+        )
+        return np.stack(results)
+
+    return lifted