Fix fitness_criterion='min' ignored in best-genome tracking, stagnation, reproduction, crossover, and statistics

The fitness_criterion config parameter was only used for the termination
check. All other fitness comparisons hardcoded "higher is better",
making fitness_criterion='min' fundamentally broken (GitHub issue #187).

Added is_better_fitness(), meets_threshold(), and worst_fitness() methods
to Config as the single source of truth for fitness direction. Updated
population.py, stagnation.py, reproduction.py, genome.py, and
statistics.py to use direction-aware comparisons throughout.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: CodeReclaimers

neat/config.py

@@ -156,6 +156,29 @@ class Config:
                 ConfigParameter('no_fitness_termination', bool, False),
                 ConfigParameter('seed', int, None, optional=True)]
 
+    def is_better_fitness(self, a, b):
+        """Return True if fitness value *a* is strictly better than *b*.
+
+        'Better' means higher when fitness_criterion is 'max' or 'mean',
+        and lower when fitness_criterion is 'min'.
+        """
+        if self.fitness_criterion == 'min':
+            return a < b
+        return a > b
+
+    def meets_threshold(self, fitness_value, threshold):
+        """Return True if *fitness_value* satisfies the termination threshold."""
+        if self.fitness_criterion == 'min':
+            return fitness_value <= threshold
+        return fitness_value >= threshold
+
+    def worst_fitness(self):
+        """Return a sentinel value worse than any real fitness."""
+        import sys
+        if self.fitness_criterion == 'min':
+            return sys.float_info.max
+        return -sys.float_info.max
+
     def __init__(self, genome_type, reproduction_type, species_set_type, stagnation_type, filename, config_information=None):
         # Check that the provided types have the required methods.
         assert hasattr(genome_type, 'parse_config')

neat/genome.py

@@ -264,17 +264,24 @@ def configure_new(self, config):
                         sep='\n', file=sys.stderr)
                 self.connect_partial_nodirect(config)
 
-    def configure_crossover(self, genome1, genome2, config):
+    def configure_crossover(self, genome1, genome2, config, fitness_criterion=None):
         """
         Configure a new genome by crossover from two parent genomes.
-        
+
         Implements NEAT paper (Stanley & Miikkulainen, 2002, p. 108) crossover:
         "When crossing over, the genes in both genomes with the same innovation
         numbers are lined up. Genes are randomly chosen from either parent at
         matching genes, whereas all excess or disjoint genes are always included
         from the more fit parent."
+
+        *fitness_criterion* controls which parent is considered fitter.
+        When 'min', lower fitness is better.  Defaults to 'max' if not provided.
         """
-        if genome1.fitness > genome2.fitness:
+        if fitness_criterion == 'min':
+            better = genome1.fitness < genome2.fitness
+        else:
+            better = genome1.fitness > genome2.fitness
+        if better:
             parent1, parent2 = genome1, genome2
         else:
             parent1, parent2 = genome2, genome1

neat/population.py

@@ -109,18 +109,18 @@ def run(self, fitness_function, n=None):
                 if g.fitness is None:
                     raise RuntimeError(f"Fitness not assigned to genome {g.key}")
 
-                if best is None or g.fitness > best.fitness:
+                if best is None or self.config.is_better_fitness(g.fitness, best.fitness):
                     best = g
             self.reporters.post_evaluate(self.config, self.population, self.species, best)
 
             # Track the best genome ever seen.
-            if self.best_genome is None or best.fitness > self.best_genome.fitness:
+            if self.best_genome is None or self.config.is_better_fitness(best.fitness, self.best_genome.fitness):
                 self.best_genome = best
 
             if not self.config.no_fitness_termination:
                 # End if the fitness threshold is reached.
                 fv = self.fitness_criterion(g.fitness for g in self.population.values())
-                if fv >= self.config.fitness_threshold:
+                if self.config.meets_threshold(fv, self.config.fitness_threshold):
                     self.reporters.found_solution(self.config, self.generation, best)
                     break
 

neat/reproduction.py

@@ -200,7 +200,7 @@ def reproduce(self, config, species, pop_size, generation):
         # interfering with the shared fitness scheme.
         all_fitnesses = []
         remaining_species = []
-        for stag_sid, stag_s, stagnant in self.stagnation.update(species, generation):
+        for stag_sid, stag_s, stagnant in self.stagnation.update(species, generation, config):
             if stagnant:
                 self.reporters.species_stagnant(stag_sid, stag_s)
             else:
@@ -228,6 +228,9 @@ def reproduce(self, config, species, pop_size, generation):
                     afs.adjusted_fitness += shift
         else:
             # Default 'normalized' behavior: normalize to [0, 1] based on population min/max.
+            # Higher adjusted fitness always means more offspring, so when
+            # fitness_criterion is 'min' the mapping is inverted: the species
+            # with the lowest raw fitness gets the highest adjusted fitness.
             min_fitness = min(all_fitnesses)
             max_fitness = max(all_fitnesses)
             # Do not allow the fitness range to be zero, as we divide by it below.
@@ -236,6 +239,8 @@ def reproduce(self, config, species, pop_size, generation):
             for afs in remaining_species:
                 msf = mean([m.fitness for m in afs.members.values()])
                 af = (msf - min_fitness) / fitness_range
+                if config.fitness_criterion == 'min':
+                    af = 1.0 - af
                 afs.adjusted_fitness = af
 
         adjusted_fitnesses = [s.adjusted_fitness for s in remaining_species]
@@ -272,10 +277,13 @@ def reproduce(self, config, species, pop_size, generation):
             s.members = {}
             species.species[s.key] = s
 
-            # Sort members in order of descending fitness, with genome id as a
-            # deterministic tie-breaker so that ordering (and thus parent
-            # selection) is reproducible across runs and checkpoint restores.
-            old_members.sort(reverse=True, key=lambda x: (x[1].fitness, x[0]))
+            # Sort members in order of descending fitness (best first), with
+            # genome id as a deterministic tie-breaker so that ordering (and
+            # thus parent selection) is reproducible across runs and checkpoint
+            # restores.  When fitness_criterion is 'min', lower fitness is
+            # better, so we sort in ascending order instead.
+            ascending = (config.fitness_criterion == 'min')
+            old_members.sort(reverse=not ascending, key=lambda x: (x[1].fitness, x[0]))
 
             # Transfer elites to new generation.
             if self.reproduction_config.elitism > 0:
@@ -315,7 +323,8 @@ def reproduce(self, config, species, pop_size, generation):
                 # genetically identical clone of the parent (but with a different ID).
                 gid = next(self.genome_indexer)
                 child = config.genome_type(gid)
-                child.configure_crossover(parent1, parent2, config.genome_config)
+                child.configure_crossover(parent1, parent2, config.genome_config,
+                                         fitness_criterion=config.fitness_criterion)
                 child.mutate(config.genome_config)
                 new_population[gid] = child
                 self.ancestors[gid] = (parent1_id, parent2_id)

neat/stagnation.py

@@ -30,14 +30,18 @@ def __init__(self, config, reporters):
 
         self.reporters = reporters
 
-    def update(self, species_set, generation):
+    def update(self, species_set, generation, config=None):
         """
         Required interface method. Updates species fitness history information,
         checking for ones that have not improved in max_stagnation generations,
         and - unless it would result in the number of species dropping below the configured
         species_elitism parameter if they were removed,
         in which case the highest-fitness species are spared -
         returns a list with stagnant species marked for removal.
+
+        The *config* parameter (top-level Config object) is used to determine
+        the fitness direction (max vs min).  When omitted, higher fitness is
+        assumed to be better (backward compatibility).
         """
         species_data = []
         # Iterate species in a deterministic order (by species id) so that
@@ -46,20 +50,29 @@ def update(self, species_set, generation):
         for sid in sorted(species_set.species.keys()):
             s = species_set.species[sid]
             if s.fitness_history:
-                prev_fitness = max(s.fitness_history)
+                if config is not None:
+                    prev_fitness = (min if config.fitness_criterion == 'min' else max)(s.fitness_history)
+                else:
+                    prev_fitness = max(s.fitness_history)
             else:
-                prev_fitness = -sys.float_info.max
+                prev_fitness = config.worst_fitness() if config is not None else -sys.float_info.max
 
             s.fitness = self.species_fitness_func(s.get_fitnesses())
             s.fitness_history.append(s.fitness)
             s.adjusted_fitness = None
-            if prev_fitness is None or s.fitness > prev_fitness:
+            if config is not None:
+                improved = config.is_better_fitness(s.fitness, prev_fitness)
+            else:
+                improved = s.fitness > prev_fitness
+            if improved:
                 s.last_improved = generation
 
             species_data.append((sid, s))
 
-        # Sort in ascending fitness order.
-        species_data.sort(key=lambda x: x[1].fitness)
+        # Sort in ascending fitness order (least fit first, so they are
+        # candidates for stagnation removal before the fittest species).
+        reverse = (config is not None and config.fitness_criterion == 'min')
+        species_data.sort(key=lambda x: x[1].fitness, reverse=reverse)
 
         result = []
         species_fitnesses = []

neat/statistics.py

@@ -22,8 +22,12 @@ def __init__(self):
         BaseReporter.__init__(self)
         self.most_fit_genomes = []
         self.generation_statistics = []
+        self._fitness_criterion = None
 
     def post_evaluate(self, config, population, species, best_genome):
+        # Remember the fitness criterion so sorting methods can use it.
+        if self._fitness_criterion is None:
+            self._fitness_criterion = getattr(config, 'fitness_criterion', 'max')
         self.most_fit_genomes.append(copy.deepcopy(best_genome))
 
         # Store the fitnesses of the members of each currently active species.
@@ -61,18 +65,14 @@ def best_unique_genomes(self, n):
             best_unique[g.key] = g
         best_unique_list = list(best_unique.values())
 
-        def key(genome):
-            return genome.fitness
-
-        return sorted(best_unique_list, key=key, reverse=True)[:n]
+        # When fitness_criterion is 'min', lower fitness is better.
+        descending = (self._fitness_criterion != 'min')
+        return sorted(best_unique_list, key=lambda g: g.fitness, reverse=descending)[:n]
 
     def best_genomes(self, n):
         """Returns the n most fit genomes ever seen."""
-
-        def key(g):
-            return g.fitness
-
-        return sorted(self.most_fit_genomes, key=key, reverse=True)[:n]
+        descending = (self._fitness_criterion != 'min')
+        return sorted(self.most_fit_genomes, key=lambda g: g.fitness, reverse=descending)[:n]
 
     def best_genome(self):
         """Returns the most fit genome ever seen."""

tests/test_fitness_evaluation.py

@@ -124,26 +124,49 @@ def fitness_function(genomes, config):
 
     def test_fitness_criterion_min(self):
         """
-        Test that 'min' fitness criterion selects minimum fitness.
-        
-        Should terminate when min fitness reaches threshold.
+        Test that 'min' fitness criterion treats lower fitness as better.
+
+        With fitness_criterion='min', termination occurs when the population's
+        minimum fitness is at or below the threshold (i.e., the best genome
+        has reached a sufficiently low fitness value).
         """
         self.config.fitness_criterion = 'min'
         self.config.fitness_threshold = 0.5
         pop = neat.Population(self.config)
-        
+
         generation_count = [0]
-        
+
         def fitness_function(genomes, config):
             generation_count[0] += 1
             for i, (genome_id, genome) in enumerate(genomes):
-                # All genomes get fitness >= 0.5
-                genome.fitness = 0.6 + i * 0.1
-        
+                # All genomes get fitness <= 0.5 (meeting the 'min' threshold)
+                genome.fitness = 0.3 + i * 0.01
+
         result = pop.run(fitness_function, 10)
-        
-        # Should terminate after 1 generation (min = 0.6 >= 0.5)
+
+        # Should terminate after 1 generation (min = 0.3 <= 0.5)
         self.assertEqual(generation_count[0], 1)
+
+    def test_fitness_criterion_min_no_early_termination(self):
+        """
+        Test that 'min' criterion does NOT terminate when fitness is above threshold.
+        """
+        self.config.fitness_criterion = 'min'
+        self.config.fitness_threshold = 0.5
+        pop = neat.Population(self.config)
+
+        generation_count = [0]
+
+        def fitness_function(genomes, config):
+            generation_count[0] += 1
+            for i, (genome_id, genome) in enumerate(genomes):
+                # All genomes have fitness above the threshold
+                genome.fitness = 0.6 + i * 0.1
+
+        result = pop.run(fitness_function, 3)
+
+        # Should NOT terminate early — min fitness (0.6) > threshold (0.5)
+        self.assertEqual(generation_count[0], 3)
 
     def test_fitness_criterion_mean(self):
         """