Skip to content

Population

Population management for evolutionary algorithms.

Individual

Bases: Generic[G]

An individual in the population.

Combines a genome with its evaluation results.

Source code in src/rotalabs_redqueen/core/population.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
@dataclass
class Individual(Generic[G]):
    """An individual in the population.

    Combines a genome with its evaluation results.
    """

    genome: G
    fitness: FitnessValue = field(default_factory=lambda: FitnessValue(0.0))
    behavior: BehaviorDescriptor = field(default_factory=lambda: BehaviorDescriptor(()))
    birth_generation: int = 0

    @classmethod
    def from_result(cls, genome: G, result: FitnessResult, generation: int = 0) -> Individual[G]:
        """Create individual from fitness result.

        Args:
            genome: The genome
            result: Fitness evaluation result
            generation: Birth generation

        Returns:
            New individual
        """
        return cls(
            genome=genome,
            fitness=result.fitness,
            behavior=result.behavior,
            birth_generation=generation,
        )

    def __lt__(self, other: Individual[G]) -> bool:
        return self.fitness < other.fitness

    def __le__(self, other: Individual[G]) -> bool:
        return self.fitness <= other.fitness

    def __gt__(self, other: Individual[G]) -> bool:
        return self.fitness > other.fitness

    def __ge__(self, other: Individual[G]) -> bool:
        return self.fitness >= other.fitness

from_result(genome: G, result: FitnessResult, generation: int = 0) -> Individual[G] classmethod

Create individual from fitness result.

Parameters:

Name Type Description Default
genome G

The genome

 required
result FitnessResult

Fitness evaluation result

 required
generation int

Birth generation

 0

Returns:

Type Description
Individual[G]

New individual
Source code in src/rotalabs_redqueen/core/population.py 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
@classmethod
def from_result(cls, genome: G, result: FitnessResult, generation: int = 0) -> Individual[G]:
    """Create individual from fitness result.

    Args:
        genome: The genome
        result: Fitness evaluation result
        generation: Birth generation

    Returns:
        New individual
    """
    return cls(
        genome=genome,
        fitness=result.fitness,
        behavior=result.behavior,
        birth_generation=generation,
    )

Population

Bases: Generic[G]

A population of individuals.

Manages individuals across generations with selection and replacement.

Source code in src/rotalabs_redqueen/core/population.py 
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
class Population(Generic[G]):
    """A population of individuals.

    Manages individuals across generations with selection and replacement.
    """

    def __init__(
        self,
        individuals: list[Individual[G]] | None = None,
        config: PopulationConfig | None = None,
        generation: int = 0,
    ):
        """Initialize population.

        Args:
            individuals: Initial individuals (or empty)
            config: Population configuration
            generation: Current generation number
        """
        self.individuals: list[Individual[G]] = individuals or []
        self.config = config or PopulationConfig()
        self.generation = generation

    @classmethod
    def random(
        cls,
        genome_class: type[G],
        size: int,
        rng: np.random.Generator | None = None,
    ) -> Population[G]:
        """Create a population of random individuals.

        Args:
            genome_class: Genome class with random() method
            size: Population size
            rng: Random number generator

        Returns:
            New population with random genomes (unevaluated)
        """
        individuals = [
            Individual(genome=genome_class.random(rng)) for _ in range(size)
        ]
        return cls(individuals=individuals, config=PopulationConfig(size=size))

    def __len__(self) -> int:
        return len(self.individuals)

    def __getitem__(self, idx: int) -> Individual[G]:
        return self.individuals[idx]

    def __iter__(self):
        return iter(self.individuals)

    def add(self, individual: Individual[G]) -> None:
        """Add an individual to the population."""
        self.individuals.append(individual)

    def best(self) -> Individual[G] | None:
        """Get the best individual by fitness.

        Returns:
            Best individual or None if empty
        """
        if not self.individuals:
            return None
        return max(self.individuals, key=lambda i: i.fitness.value)

    def top_n(self, n: int) -> list[Individual[G]]:
        """Get the top N individuals by fitness.

        Args:
            n: Number of individuals to return

        Returns:
            List of top N individuals, sorted by fitness (best first)
        """
        return sorted(self.individuals, key=lambda i: i.fitness.value, reverse=True)[:n]

    def tournament_select(
        self,
        tournament_size: int = 3,
        rng: np.random.Generator | None = None,
    ) -> Individual[G]:
        """Select an individual via tournament selection.

        Args:
            tournament_size: Number of individuals in tournament
            rng: Random number generator

        Returns:
            Winner of tournament (best fitness)
        """
        if rng is None:
            rng = np.random.default_rng()

        indices = rng.choice(len(self.individuals), size=tournament_size, replace=False)
        contestants = [self.individuals[i] for i in indices]
        return max(contestants, key=lambda i: i.fitness.value)

    def select_parents(
        self,
        n: int,
        tournament_size: int = 3,
        rng: np.random.Generator | None = None,
    ) -> list[Individual[G]]:
        """Select N parents via tournament selection.

        Args:
            n: Number of parents to select
            tournament_size: Tournament size
            rng: Random number generator

        Returns:
            List of selected parents
        """
        return [self.tournament_select(tournament_size, rng) for _ in range(n)]

    def average_fitness(self) -> float:
        """Get average fitness of population."""
        if not self.individuals:
            return 0.0
        return sum(i.fitness.value for i in self.individuals) / len(self.individuals)

    def fitness_std(self) -> float:
        """Get standard deviation of fitness."""
        if len(self.individuals) < 2:
            return 0.0
        values = [i.fitness.value for i in self.individuals]
        return float(np.std(values))

    def diversity(self) -> float:
        """Measure population diversity using average pairwise distance.

        Returns:
            Average behavior distance between individuals
        """
        if len(self.individuals) < 2:
            return 0.0

        total = 0.0
        count = 0
        for i, ind1 in enumerate(self.individuals):
            for ind2 in self.individuals[i + 1:]:
                total += ind1.behavior.distance(ind2.behavior)
                count += 1

        return total / count if count > 0 else 0.0

__init__(individuals: list[Individual[G]] | None = None, config: PopulationConfig | None = None, generation: int = 0)

Initialize population.

Parameters:

Name Type Description Default
individuals list[Individual[G]] | None

Initial individuals (or empty)

 None
config PopulationConfig | None

Population configuration

 None
generation int

Current generation number

 0
Source code in src/rotalabs_redqueen/core/population.py 
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
def __init__(
    self,
    individuals: list[Individual[G]] | None = None,
    config: PopulationConfig | None = None,
    generation: int = 0,
):
    """Initialize population.

    Args:
        individuals: Initial individuals (or empty)
        config: Population configuration
        generation: Current generation number
    """
    self.individuals: list[Individual[G]] = individuals or []
    self.config = config or PopulationConfig()
    self.generation = generation

random(genome_class: type[G], size: int, rng: np.random.Generator | None = None) -> Population[G] classmethod

Create a population of random individuals.

Parameters:

Name Type Description Default
genome_class type[G]

Genome class with random() method

 required
size int

Population size

 required
rng Generator | None

Random number generator

 None

Returns:

Type Description
Population[G]

New population with random genomes (unevaluated)
Source code in src/rotalabs_redqueen/core/population.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
@classmethod
def random(
    cls,
    genome_class: type[G],
    size: int,
    rng: np.random.Generator | None = None,
) -> Population[G]:
    """Create a population of random individuals.

    Args:
        genome_class: Genome class with random() method
        size: Population size
        rng: Random number generator

    Returns:
        New population with random genomes (unevaluated)
    """
    individuals = [
        Individual(genome=genome_class.random(rng)) for _ in range(size)
    ]
    return cls(individuals=individuals, config=PopulationConfig(size=size))

add(individual: Individual[G]) -> None

Add an individual to the population.

Source code in src/rotalabs_redqueen/core/population.py 
126
127
128
def add(self, individual: Individual[G]) -> None:
    """Add an individual to the population."""
    self.individuals.append(individual)

best() -> Individual[G] | None

Get the best individual by fitness.

Returns:

Type Description
Individual[G] | None

Best individual or None if empty
Source code in src/rotalabs_redqueen/core/population.py 
130
131
132
133
134
135
136
137
138
def best(self) -> Individual[G] | None:
    """Get the best individual by fitness.

    Returns:
        Best individual or None if empty
    """
    if not self.individuals:
        return None
    return max(self.individuals, key=lambda i: i.fitness.value)

top_n(n: int) -> list[Individual[G]]

Get the top N individuals by fitness.

Parameters:

Name Type Description Default
n int

Number of individuals to return

 required

Returns:

Type Description
list[Individual[G]]

List of top N individuals, sorted by fitness (best first)
Source code in src/rotalabs_redqueen/core/population.py 
140
141
142
143
144
145
146
147
148
149
def top_n(self, n: int) -> list[Individual[G]]:
    """Get the top N individuals by fitness.

    Args:
        n: Number of individuals to return

    Returns:
        List of top N individuals, sorted by fitness (best first)
    """
    return sorted(self.individuals, key=lambda i: i.fitness.value, reverse=True)[:n]

tournament_select(tournament_size: int = 3, rng: np.random.Generator | None = None) -> Individual[G]

Select an individual via tournament selection.

Parameters:

Name Type Description Default
tournament_size int

Number of individuals in tournament

 3
rng Generator | None

Random number generator

 None

Returns:

Type Description
Individual[G]

Winner of tournament (best fitness)
Source code in src/rotalabs_redqueen/core/population.py 
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
def tournament_select(
    self,
    tournament_size: int = 3,
    rng: np.random.Generator | None = None,
) -> Individual[G]:
    """Select an individual via tournament selection.

    Args:
        tournament_size: Number of individuals in tournament
        rng: Random number generator

    Returns:
        Winner of tournament (best fitness)
    """
    if rng is None:
        rng = np.random.default_rng()

    indices = rng.choice(len(self.individuals), size=tournament_size, replace=False)
    contestants = [self.individuals[i] for i in indices]
    return max(contestants, key=lambda i: i.fitness.value)

select_parents(n: int, tournament_size: int = 3, rng: np.random.Generator | None = None) -> list[Individual[G]]

Select N parents via tournament selection.

Parameters:

Name Type Description Default
n int

Number of parents to select

 required
tournament_size int

Tournament size

 3
rng Generator | None

Random number generator

 None

Returns:

Type Description
list[Individual[G]]

List of selected parents
Source code in src/rotalabs_redqueen/core/population.py 
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
def select_parents(
    self,
    n: int,
    tournament_size: int = 3,
    rng: np.random.Generator | None = None,
) -> list[Individual[G]]:
    """Select N parents via tournament selection.

    Args:
        n: Number of parents to select
        tournament_size: Tournament size
        rng: Random number generator

    Returns:
        List of selected parents
    """
    return [self.tournament_select(tournament_size, rng) for _ in range(n)]

average_fitness() -> float

Get average fitness of population.

Source code in src/rotalabs_redqueen/core/population.py 
190
191
192
193
194
def average_fitness(self) -> float:
    """Get average fitness of population."""
    if not self.individuals:
        return 0.0
    return sum(i.fitness.value for i in self.individuals) / len(self.individuals)

fitness_std() -> float

Get standard deviation of fitness.

Source code in src/rotalabs_redqueen/core/population.py 
196
197
198
199
200
201
def fitness_std(self) -> float:
    """Get standard deviation of fitness."""
    if len(self.individuals) < 2:
        return 0.0
    values = [i.fitness.value for i in self.individuals]
    return float(np.std(values))

diversity() -> float

Measure population diversity using average pairwise distance.

Returns:

Type Description
float

Average behavior distance between individuals
Source code in src/rotalabs_redqueen/core/population.py 
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
def diversity(self) -> float:
    """Measure population diversity using average pairwise distance.

    Returns:
        Average behavior distance between individuals
    """
    if len(self.individuals) < 2:
        return 0.0

    total = 0.0
    count = 0
    for i, ind1 in enumerate(self.individuals):
        for ind2 in self.individuals[i + 1:]:
            total += ind1.behavior.distance(ind2.behavior)
            count += 1

    return total / count if count > 0 else 0.0

PopulationConfig

Configuration for population management.

Source code in src/rotalabs_redqueen/core/population.py 
64
65
66
67
68
69
@dataclass
class PopulationConfig:
    """Configuration for population management."""

    size: int = 100
    elitism: int = 1  # Number of best individuals to preserve