ctrl-freak 0.1.0__py3-none-any.whl

ctrl_freak/operators/selection.py

@@ -0,0 +1,144 @@
+"""Selection and offspring creation operators for NSGA-II.
+
+This module provides:
+- select_parents: Binary tournament selection using crowded comparison
+- create_offspring: Create offspring via selection, crossover, and mutation
+"""
+
+from collections.abc import Callable
+
+import numpy as np
+
+from ctrl_freak.population import Population
+
+
+def select_parents(
+    pop: Population,
+    n_parents: int,
+    rng: np.random.Generator,
+    rank: np.ndarray,
+    crowding_distance: np.ndarray,
+) -> np.ndarray:
+    """Select parents using binary tournament selection (vectorized).
+
+    Uses the crowded comparison operator: lower rank wins, ties broken by
+    higher crowding distance.
+
+    Parameters
+    ----------
+    pop : Population
+        Population used for its size.
+    n_parents : int
+        Number of parents to select.
+    rng : numpy.random.Generator
+        Random number generator for reproducibility.
+    rank : numpy.ndarray
+        Pareto front ranks for all individuals. Shape is ``(n,)``.
+    crowding_distance : numpy.ndarray
+        Crowding distances for all individuals. Shape is ``(n,)``.
+
+    Returns
+    -------
+    numpy.ndarray
+        Array of shape ``(n_parents,)`` containing indices into ``pop``.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from ctrl_freak.population import Population
+    >>> from ctrl_freak.operators.selection import select_parents
+    >>> pop = Population(x=np.zeros((4, 2)), objectives=np.zeros((4, 2)))
+    >>> rng = np.random.default_rng(0)
+    >>> parents = select_parents(
+    ...     pop,
+    ...     n_parents=10,
+    ...     rng=rng,
+    ...     rank=np.array([0, 0, 1, 1]),
+    ...     crowding_distance=np.array([1.0, 2.0, 1.0, 2.0]),
+    ... )
+    >>> parents.shape
+    (10,)
+    """
+    n = len(pop.x)
+    candidates = rng.integers(0, n, size=(n_parents, 2))
+
+    rank_a = rank[candidates[:, 0]]
+    rank_b = rank[candidates[:, 1]]
+    cd_a = crowding_distance[candidates[:, 0]]
+    cd_b = crowding_distance[candidates[:, 1]]
+
+    # a wins if: lower rank OR (same rank AND higher or equal crowding distance)
+    a_wins = (rank_a < rank_b) | ((rank_a == rank_b) & (cd_a >= cd_b))
+
+    return np.where(a_wins, candidates[:, 0], candidates[:, 1])
+
+
+def create_offspring(
+    pop: Population,
+    n_offspring: int,
+    crossover: Callable[[np.ndarray, np.ndarray], np.ndarray],
+    mutate: Callable[[np.ndarray], np.ndarray],
+    rng: np.random.Generator,
+    rank: np.ndarray,
+    crowding_distance: np.ndarray,
+) -> np.ndarray:
+    """Create offspring via selection, crossover, and mutation.
+
+    Selects 2*n_offspring parents using binary tournament, crosses them
+    in pairs, and applies mutation to all offspring.
+
+    Parameters
+    ----------
+    pop : Population
+        Parent population.
+    n_offspring : int
+        Number of offspring to create.
+    crossover : Callable[[numpy.ndarray, numpy.ndarray], numpy.ndarray]
+        Crossover function with signature ``(n_vars,), (n_vars,) -> (n_vars,)``.
+    mutate : Callable[[numpy.ndarray], numpy.ndarray]
+        Mutation function with signature ``(n_vars,) -> (n_vars,)``.
+    rng : numpy.random.Generator
+        Random number generator for reproducibility.
+    rank : numpy.ndarray
+        Pareto front ranks for all individuals. Shape is ``(n,)``.
+    crowding_distance : numpy.ndarray
+        Crowding distances for all individuals. Shape is ``(n,)``.
+
+    Returns
+    -------
+    numpy.ndarray
+        Array of shape ``(n_offspring, n_vars)`` containing unevaluated
+        offspring decision variables.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from ctrl_freak.population import Population
+    >>> from ctrl_freak.operators.selection import create_offspring
+    >>> pop = Population(x=np.arange(8.0).reshape(4, 2), objectives=np.zeros((4, 2)))
+    >>> rng = np.random.default_rng(0)
+    >>> crossover = lambda p1, p2: (p1 + p2) / 2
+    >>> mutate = lambda x: x.copy()
+    >>> offspring = create_offspring(
+    ...     pop,
+    ...     n_offspring=3,
+    ...     crossover=crossover,
+    ...     mutate=mutate,
+    ...     rng=rng,
+    ...     rank=np.array([0, 0, 1, 1]),
+    ...     crowding_distance=np.array([1.0, 2.0, 1.0, 2.0]),
+    ... )
+    >>> offspring.shape
+    (3, 2)
+    """
+    parent_idx = select_parents(pop, n_offspring * 2, rng, rank=rank, crowding_distance=crowding_distance)
+
+    # Crossover pairs (2i, 2i+1) to get n_offspring children
+    offspring_x = np.stack(
+        [crossover(pop.x[parent_idx[2 * i]], pop.x[parent_idx[2 * i + 1]]) for i in range(n_offspring)]
+    )
+
+    # Mutate all offspring
+    offspring_x = np.stack([mutate(x) for x in offspring_x])
+
+    return offspring_x

ctrl_freak/operators/standard.py

@@ -0,0 +1,275 @@
+"""Standard bounded genetic operators for NSGA-II.
+
+This module provides Simulated Binary Crossover (SBX) and polynomial mutation
+operators for real-valued decision vectors.
+
+Seed-injection contract (consumed by the algorithm layer): `sbx_crossover(...)`
+and `polynomial_mutation(...)` return callable operator objects. Each exposes
+`set_rng(rng: numpy.random.Generator) -> None`, which replaces the operator's
+internal generator. Until `set_rng` is called, the operator uses the generator
+built from its constructor `seed=`. The call signatures are unchanged:
+`crossover(p1, p2) -> child`, `mutate(x) -> x'`. Algorithms unify
+reproducibility by calling `set_rng` with a `SeedSequence.spawn`-derived
+generator after constructing operators; standalone users may ignore `set_rng`
+and rely on `seed=`.
+"""
+
+from collections.abc import Callable
+
+import numpy as np
+
+Bounds = tuple[float, float] | tuple[np.ndarray, np.ndarray]
+"""Bounds for decision variables.
+
+A scalar pair ``(lower, upper)`` applies the same bounds to all variables.
+A pair of arrays ``(lower_array, upper_array)`` specifies per-variable bounds.
+"""
+
+
+class _SeededOperator:
+    """Mixin providing an injectable numpy Generator for genetic operators.
+
+    The operator owns a ``numpy.random.Generator`` built from ``seed`` at
+    construction. An orchestrating algorithm may replace it post-construction
+    via :meth:`set_rng` so a single master seed reproduces the entire run.
+    """
+
+    _rng: np.random.Generator
+
+    def set_rng(self, rng: np.random.Generator) -> None:
+        """Inject a numpy Generator, replacing the operator's internal RNG.
+
+        Parameters
+        ----------
+        rng : numpy.random.Generator
+            Generator to use for all subsequent draws. Replaces the generator
+            built from the constructor ``seed``.
+        """
+        self._rng = rng
+
+
+class _SBXCrossover(_SeededOperator):
+    """Callable bounded Simulated Binary Crossover operator."""
+
+    def __init__(self, eta: float, bounds: Bounds, seed: int | None) -> None:
+        self.eta = float(eta)
+        self.bounds = bounds
+        self._rng = np.random.default_rng(seed)
+
+    def __call__(self, p1: np.ndarray, p2: np.ndarray) -> np.ndarray:
+        """Apply bounded SBX to two parents and return one child.
+
+        Parameters
+        ----------
+        p1 : numpy.ndarray
+            First parent decision vector.
+        p2 : numpy.ndarray
+            Second parent decision vector.
+
+        Returns
+        -------
+        numpy.ndarray
+            One child decision vector with the same shape as ``p1``.
+        """
+        eps = 1e-14
+        eta = self.eta
+        exponent = 1.0 / (eta + 1.0)
+        rng = self._rng
+
+        lower, upper = self.bounds
+        xl = np.broadcast_to(np.asarray(lower, dtype=float), p1.shape)
+        xu = np.broadcast_to(np.asarray(upper, dtype=float), p1.shape)
+
+        sm = p1 < p2
+        y1 = np.where(sm, p1, p2)
+        y2 = np.where(sm, p2, p1)
+
+        eligible = (np.abs(p1 - p2) > eps) & (xl < xu)
+        delta = np.where(eligible, y2 - y1, 1.0)
+
+        rand = rng.random(p1.shape[0])
+
+        def calc_betaq(beta: np.ndarray) -> np.ndarray:
+            alpha = 2.0 - np.power(beta, -(eta + 1.0))
+            mask = rand <= (1.0 / alpha)
+            return np.where(
+                mask,
+                np.power(rand * alpha, exponent),
+                np.power(1.0 / (2.0 - rand * alpha), exponent),
+            )
+
+        beta1 = 1.0 + (2.0 * (y1 - xl) / delta)
+        c1 = 0.5 * ((y1 + y2) - calc_betaq(beta1) * delta)
+
+        beta2 = 1.0 + (2.0 * (xu - y2) / delta)
+        c2 = 0.5 * ((y1 + y2) + calc_betaq(beta2) * delta)
+
+        child_for_p1 = np.where(sm, c1, c2)
+        child_for_p2 = np.where(sm, c2, c1)
+        child = np.where(rng.random(p1.shape[0]) < 0.5, child_for_p1, child_for_p2)
+        child = np.where(eligible, child, p1)
+        return np.clip(child, xl, xu)
+
+
+class _PolynomialMutation(_SeededOperator):
+    """Callable bounded polynomial mutation operator."""
+
+    def __init__(self, eta: float, prob: float | None, bounds: Bounds, seed: int | None) -> None:
+        self.eta = float(eta)
+        self.prob = prob
+        self.bounds = bounds
+        self._rng = np.random.default_rng(seed)
+
+    def __call__(self, x: np.ndarray) -> np.ndarray:
+        """Apply polynomial mutation to an individual.
+
+        Parameters
+        ----------
+        x : numpy.ndarray
+            Decision vector to mutate.
+
+        Returns
+        -------
+        numpy.ndarray
+            Mutated decision vector with the same shape as ``x``.
+        """
+        n_vars = len(x)
+        mutation_prob = self.prob if self.prob is not None else 1.0 / n_vars
+        mutation_mask = self._rng.random(n_vars) < mutation_prob
+
+        if not np.any(mutation_mask):
+            return x.copy()
+
+        lower, upper = self.bounds
+        lower_arr = np.broadcast_to(np.asarray(lower, dtype=float), x.shape)
+        upper_arr = np.broadcast_to(np.asarray(upper, dtype=float), x.shape)
+        delta_max = upper_arr - lower_arr
+        degenerate = delta_max == 0
+        safe_delta = np.where(degenerate, 1.0, delta_max)
+
+        delta_l = (x - lower_arr) / safe_delta
+        delta_r = (upper_arr - x) / safe_delta
+
+        u = self._rng.random(n_vars)
+
+        xy_left = 1.0 - delta_l
+        val_left = 2.0 * u + (1.0 - 2.0 * u) * (xy_left ** (self.eta + 1.0))
+        delta_q_left = val_left ** (1.0 / (self.eta + 1.0)) - 1.0
+
+        xy_right = 1.0 - delta_r
+        val_right = 2.0 * (1.0 - u) + 2.0 * (u - 0.5) * (xy_right ** (self.eta + 1.0))
+        delta_q_right = 1.0 - val_right ** (1.0 / (self.eta + 1.0))
+
+        delta_q = np.where(u < 0.5, delta_q_left, delta_q_right)
+
+        effective_mask = mutation_mask & ~degenerate
+        mutated = np.where(effective_mask, x + delta_q * delta_max, x)
+        return np.clip(mutated, lower_arr, upper_arr)
+
+
+def sbx_crossover(
+    eta: float = 15.0,
+    bounds: Bounds = (0.0, 1.0),
+    seed: int | None = None,
+) -> Callable[[np.ndarray, np.ndarray], np.ndarray]:
+    """Create a bounded Simulated Binary Crossover operator.
+
+    Parameters
+    ----------
+    eta : float, default=15.0
+        Distribution index. Higher values produce children closer to parents.
+    bounds : tuple, default=(0.0, 1.0)
+        Lower and upper decision-variable bounds. Scalars apply to all
+        variables; arrays provide per-variable bounds.
+    seed : int, optional
+        Random seed for the standalone generator used until ``set_rng`` is
+        called.
+
+    Returns
+    -------
+    collections.abc.Callable
+        Callable with signature ``(p1, p2) -> child``. The returned object also
+        exposes ``set_rng(rng)`` for algorithm-level seed injection.
+
+    References
+    ----------
+    Deb, K., & Agrawal, R. B. (1995). Simulated binary crossover for
+    continuous search space. Complex Systems, 9(2), 115-148.
+
+    Examples
+    --------
+    >>> crossover = sbx_crossover(eta=15.0, bounds=(0.0, 1.0), seed=42)
+    >>> p1 = np.array([0.2, 0.4, 0.6])
+    >>> p2 = np.array([0.3, 0.5, 0.7])
+    >>> child = crossover(p1, p2)
+    >>> child.shape
+    (3,)
+
+    Per-variable bounds:
+
+    >>> lower = np.array([0.0, -10.0, 100.0])
+    >>> upper = np.array([1.0, 10.0, 200.0])
+    >>> crossover = sbx_crossover(eta=15.0, bounds=(lower, upper), seed=42)
+    >>> crossover(np.array([0.5, 0.0, 150.0]), np.array([0.8, -5.0, 180.0])).shape
+    (3,)
+
+    Seed injection:
+
+    >>> cx = sbx_crossover(eta=15.0, bounds=(0.0, 1.0), seed=0)
+    >>> cx.set_rng(np.random.default_rng(123))
+    >>> child = cx(np.array([0.2, 0.4]), np.array([0.6, 0.8]))
+    >>> child.shape
+    (2,)
+    """
+    return _SBXCrossover(eta=eta, bounds=bounds, seed=seed)
+
+
+def polynomial_mutation(
+    eta: float = 20.0,
+    prob: float | None = None,
+    bounds: Bounds = (0.0, 1.0),
+    seed: int | None = None,
+) -> Callable[[np.ndarray], np.ndarray]:
+    """Create a bounded polynomial mutation operator.
+
+    Parameters
+    ----------
+    eta : float, default=20.0
+        Distribution index. Higher values produce smaller perturbations.
+    prob : float, optional
+        Mutation probability per variable. If omitted, uses ``1 / n_vars``.
+    bounds : tuple, default=(0.0, 1.0)
+        Lower and upper decision-variable bounds. Scalars apply to all
+        variables; arrays provide per-variable bounds.
+    seed : int, optional
+        Random seed for the standalone generator used until ``set_rng`` is
+        called.
+
+    Returns
+    -------
+    collections.abc.Callable
+        Callable with signature ``x -> x'``. The returned object also exposes
+        ``set_rng(rng)`` for algorithm-level seed injection.
+
+    References
+    ----------
+    Deb, K., & Goyal, M. (1996). A combined genetic adaptive search (GeneAS)
+    for engineering design. Computer Science and Informatics, 26(4), 30-45.
+
+    Examples
+    --------
+    >>> mutate = polynomial_mutation(eta=20.0, prob=0.1, bounds=(0.0, 1.0), seed=42)
+    >>> x = np.array([0.5, 0.5, 0.5])
+    >>> mutated = mutate(x)
+    >>> mutated.shape
+    (3,)
+
+    Per-variable bounds:
+
+    >>> lower = np.array([0.0, -10.0, 100.0])
+    >>> upper = np.array([1.0, 10.0, 200.0])
+    >>> mutate = polynomial_mutation(eta=20.0, prob=0.1, bounds=(lower, upper), seed=42)
+    >>> mutate(np.array([0.5, 0.0, 150.0])).shape
+    (3,)
+    """
+    return _PolynomialMutation(eta=eta, prob=prob, bounds=bounds, seed=seed)

ctrl_freak/population.py

@@ -0,0 +1,203 @@
+"""Population data structures for multi-objective optimization.
+
+This module provides the core data structures for representing populations
+of individuals in multi-objective optimization algorithms:
+
+- Population: A struct-of-arrays representation of multiple individuals
+- IndividualView: A read-only view of a single individual
+
+Both classes are immutable (frozen dataclasses) to enforce functional style.
+Population is algorithm-agnostic - it only stores decision variables and objectives.
+"""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class IndividualView:
+    """Read-only view of a single individual in a population.
+
+    This class provides a convenient way to access the data for a single
+    individual, returned by Population.__getitem__.
+
+    Attributes
+    ----------
+    x : numpy.ndarray
+        Decision variables for this individual.
+    objectives : numpy.ndarray | None
+        Objective values for this individual, or None.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from ctrl_freak.population import Population
+    >>> pop = Population(x=np.array([[1.0, 2.0], [3.0, 4.0]]))
+    >>> individual = pop[0]
+    >>> individual.x
+    array([1., 2.])
+    """
+
+    x: np.ndarray
+    objectives: np.ndarray | None
+
+
+@dataclass(frozen=True)
+class Population:
+    """Immutable struct-of-arrays representation of a population.
+
+    This class stores multiple individuals using a struct-of-arrays layout
+    for efficient vectorized operations. All arrays are copied on construction
+    to ensure immutability.
+
+    Population is algorithm-agnostic - it only stores decision variables and
+    objective values. Algorithm-specific data (like Pareto ranks or crowding
+    distances) should be managed separately by the algorithm implementation.
+
+    Attributes
+    ----------
+    x : numpy.ndarray
+        Decision variables for all individuals. Shape is ``(n, n_vars)``.
+    objectives : numpy.ndarray | None
+        Objective values. Shape is ``(n, n_obj)``, or None if not evaluated.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from ctrl_freak.population import Population
+    >>> 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)
+    >>> len(pop)
+    3
+    >>> pop.n_vars
+    2
+    >>> pop.n_obj
+    2
+    """
+
+    x: np.ndarray
+    objectives: np.ndarray | None = None
+
+    def __post_init__(self) -> None:
+        """Validate shapes and copy arrays for immutability.
+
+        Raises
+        ------
+        TypeError
+            If x is not a numpy array.
+        ValueError
+            If array shapes are inconsistent or invalid.
+        """
+        # Validate x
+        if not isinstance(self.x, np.ndarray):
+            raise TypeError(f"x must be a numpy array, got {type(self.x).__name__}")
+        if self.x.ndim != 2:
+            raise ValueError(f"x must be 2D, got shape {self.x.shape}")
+
+        n = self.x.shape[0]
+
+        # Copy x for immutability (use object.__setattr__ for frozen dataclass)
+        object.__setattr__(self, "x", self.x.copy())
+
+        # Validate and copy objectives
+        if self.objectives is not None:
+            if not isinstance(self.objectives, np.ndarray):
+                raise TypeError(f"objectives must be a numpy array, got {type(self.objectives).__name__}")
+            if self.objectives.ndim != 2:
+                raise ValueError(f"objectives must be 2D, got shape {self.objectives.shape}")
+            if self.objectives.shape[0] != n:
+                raise ValueError(f"objectives has {self.objectives.shape[0]} individuals, expected {n} to match x")
+            object.__setattr__(self, "objectives", self.objectives.copy())
+
+    def __len__(self) -> int:
+        """Return the number of individuals in the population.
+
+        Returns
+        -------
+        int
+            Number of individuals.
+        """
+        return self.x.shape[0]
+
+    def __getitem__(self, idx: int) -> IndividualView:
+        """Get a read-only view of a single individual.
+
+        Parameters
+        ----------
+        idx : int
+            Index of the individual. Negative indexing is supported.
+
+        Returns
+        -------
+        IndividualView
+            Data for the specified individual.
+
+        Raises
+        ------
+        TypeError
+            If idx is not an integer.
+        IndexError
+            If idx is out of bounds.
+
+        Examples
+        --------
+        >>> import numpy as np
+        >>> from ctrl_freak.population import Population
+        >>> pop = Population(x=np.array([[1.0, 2.0], [3.0, 4.0]]))
+        >>> pop[0].x
+        array([1., 2.])
+        >>> pop[-1].x
+        array([3., 4.])
+        """
+        if not isinstance(idx, (int, np.integer)):
+            raise TypeError(f"indices must be integers, got {type(idx).__name__}")
+
+        n = len(self)
+        original_idx = idx
+        # Handle negative indexing
+        if idx < 0:
+            idx = n + idx
+        if idx < 0 or idx >= n:
+            raise IndexError(f"index {original_idx} is out of bounds for population with {n} individuals")
+
+        return IndividualView(
+            x=self.x[idx],
+            objectives=self.objectives[idx] if self.objectives is not None else None,
+        )
+
+    @property
+    def n_individuals(self) -> int:
+        """Return the number of individuals in the population.
+
+        Returns
+        -------
+        int
+            Number of individuals.
+        """
+        return self.x.shape[0]
+
+    @property
+    def n_vars(self) -> int:
+        """Return the number of decision variables per individual.
+
+        Returns
+        -------
+        int
+            Number of decision variables.
+        """
+        return self.x.shape[1]
+
+    @property
+    def n_obj(self) -> int | None:
+        """Return the number of objectives, or None if not evaluated.
+
+        Returns
+        -------
+        int | None
+            Number of objectives, or None if objectives is None.
+        """
+        if self.objectives is None:
+            return None
+        return self.objectives.shape[1]

ctrl_freak/primitives/__init__.py

@@ -0,0 +1,23 @@
+"""Pareto-based ranking and diversity primitives.
+
+Examples
+--------
+>>> import numpy as np
+>>> ranks = non_dominated_sort(np.array([[1.0, 1.0], [2.0, 2.0]]))
+>>> ranks
+array([0, 1])
+"""
+
+from ctrl_freak.primitives.pareto import (
+    crowding_distance,
+    dominates,
+    dominates_matrix,
+    non_dominated_sort,
+)
+
+__all__ = [
+    "dominates",
+    "dominates_matrix",
+    "non_dominated_sort",
+    "crowding_distance",
+]