Clarify checkpoint semantics and make evolution more deterministic.

Author: CodeReclaimers

CHANGELOG.md

@@ -48,6 +48,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   without changing the public API.
 
 ### Fixed
+- **Add-node mutation bias behavior**: Newly inserted nodes created by `mutate_add_node` now start with zero bias so that splitting a connection is as neutral as possible with respect to the original signal flow. This makes the structural mutation less disruptive while preserving the existing weight-preserving semantics (incoming weight 1.0, outgoing weight equal to the original connection).
+- **Checkpoint Generation Semantics**: Clarified and corrected how checkpoint generation numbers are labeled and interpreted.
+  - A checkpoint file named `neat-checkpoint-N` now always contains the population, species state, and RNG state needed to begin evaluating **generation `N`**.
+  - Previously, checkpoints were labeled with the index of the generation that had just been evaluated, while storing the *next* generation's population; this could make restored runs appear to "repeat" the previous generation.
+  - The NEAT evolution loop and genetic algorithm behavior are unchanged; this is a bookkeeping fix that aligns checkpoint behavior with user expectations and the original NEAT paper's generational model.
+  - New and updated tests in `tests/test_checkpoint.py` and `tests/test_population.py` enforce the invariant that checkpoint `N` resumes at the start of generation `N`.
 - **Population Size Drift**: Fixed small mismatches between actual population size and configured `pop_size`
   - `DefaultReproduction.reproduce()` now strictly enforces `len(population) == config.pop_size` for every non-extinction generation
   - New `_adjust_spawn_exact` helper adjusts per-species spawn counts after `compute_spawn()` to correct rounding/clamping drift

docs/reproducibility.rst

@@ -151,6 +151,13 @@ Saving Checkpoints
    # Run evolution
    pop.run(eval_genomes, 50)
 
+In this example, checkpoints named ``neat-checkpoint-5``, ``neat-checkpoint-10``,
+``neat-checkpoint-15``, ... will be created.  The numeric suffix ``N`` always
+refers to the **next generation to be evaluated**.  In other words, a
+checkpoint labeled ``neat-checkpoint-25`` contains the population and species
+state for generation 25 at the point just before its fitness evaluation
+begins.
+
 Restoring Checkpoints
 ^^^^^^^^^^^^^^^^^^^^^^
 

neat/checkpoint.py

@@ -21,7 +21,13 @@ def __init__(self, generation_interval, time_interval_seconds=None,
         Saves the current state (at the end of a generation) every ``generation_interval`` generations or
         ``time_interval_seconds``, whichever happens first.
 
-        :param generation_interval: If not None, maximum number of generations between save intervals
+        The checkpoint filename suffix (for example, ``neat-checkpoint-10``) always refers to the
+        **next generation to be evaluated**.  In other words, a checkpoint created with suffix ``N``
+        contains the population and species state for generation ``N`` at the point just before
+        its fitness evaluation begins.
+
+        :param generation_interval: If not None, maximum number of generations between save intervals,
+                                    measured in generations-to-be-evaluated
         :type generation_interval: int or None
         :param time_interval_seconds: If not None, maximum number of seconds between checkpoint attempts
         :type time_interval_seconds: float or None
@@ -32,28 +38,51 @@ def __init__(self, generation_interval, time_interval_seconds=None,
         self.filename_prefix = filename_prefix
 
         self.current_generation = None
-        self.last_generation_checkpoint = -1
+        # Tracks the most recent generation index for which a checkpoint was created.
+        # This value is interpreted as the next generation to be evaluated when the
+        # checkpoint is restored (see above).
+        self.last_generation_checkpoint = 0
         self.last_time_checkpoint = time.time()
 
     def start_generation(self, generation):
+        """Record the index of the generation that is about to be evaluated.
+
+        Note that at the time :meth:`end_generation` is called for generation ``g``,
+        the population and species that are passed in already correspond to the
+        *next* generation (``g + 1``).  This reporter therefore uses ``g + 1`` as
+        the generation index stored in checkpoints, so that restoring a
+        checkpoint labeled ``N`` always resumes at the beginning of generation
+        ``N``.
+        """
         self.current_generation = generation
 
     def end_generation(self, config, population, species_set):
+        """Potentially save a checkpoint at the end of a generation.
+
+        The ``population`` and ``species_set`` arguments contain the state for
+        the next generation to be evaluated, whose index is
+        ``self.current_generation + 1``.
+        """
         checkpoint_due = False
 
         if self.time_interval_seconds is not None:
             dt = time.time() - self.last_time_checkpoint
             if dt >= self.time_interval_seconds:
                 checkpoint_due = True
 
-        if (checkpoint_due is False) and (self.generation_interval is not None):
-            dg = self.current_generation - self.last_generation_checkpoint
+        # The generation whose population is being saved.
+        next_generation = self.current_generation + 1
+
+        if (not checkpoint_due) and (self.generation_interval is not None):
+            # Compare the upcoming generation index against the last checkpointed
+            # generation index to decide whether a new checkpoint is due.
+            dg = next_generation - self.last_generation_checkpoint
             if dg >= self.generation_interval:
                 checkpoint_due = True
 
         if checkpoint_due:
-            self.save_checkpoint(config, population, species_set, self.current_generation)
-            self.last_generation_checkpoint = self.current_generation
+            self.save_checkpoint(config, population, species_set, next_generation)
+            self.last_generation_checkpoint = next_generation
             self.last_time_checkpoint = time.time()
 
     def save_checkpoint(self, config, population, species_set, generation):

neat/reproduction.py

@@ -236,8 +236,10 @@ def reproduce(self, config, species, pop_size, generation):
             s.members = {}
             species.species[s.key] = s
 
-            # Sort members in order of descending fitness.
-            old_members.sort(reverse=True, key=lambda x: x[1].fitness)
+            # 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]))
 
             # Transfer elites to new generation.
             if self.reproduction_config.elitism > 0:

neat/species.py

@@ -79,11 +79,15 @@ def speciate(self, config, population, generation):
         compatibility_threshold = self.species_set_config.compatibility_threshold
 
         # Find the best representatives for each existing species.
-        unspeciated = set(population)
+        # Use a deterministic ordering for unspeciated genomes so that
+        # speciation is reproducible across runs and checkpoint restores.
+        unspeciated = list(sorted(population.keys()))
         distances = GenomeDistanceCache(config.genome_config)
         new_representatives = {}
         new_members = {}
-        for sid, s in self.species.items():
+        # Iterate species in deterministic id order.
+        for sid in sorted(self.species.keys()):
+            s = self.species[sid]
             candidates = []
             for gid in unspeciated:
                 g = population[gid]
@@ -98,8 +102,9 @@ def speciate(self, config, population, generation):
             unspeciated.remove(new_rid)
 
         # Partition population into species based on genetic similarity.
+        # Iterate remaining genomes in ascending id order for determinism.
         while unspeciated:
-            gid = unspeciated.pop()
+            gid = unspeciated.pop(0)
             g = population[gid]
 
             # Find the species with the most similar representative.
@@ -122,7 +127,8 @@ def speciate(self, config, population, generation):
 
         # Update species collection based on new speciation.
         self.genome_to_species = {}
-        for sid, rid in new_representatives.items():
+        for sid in sorted(new_representatives.keys()):
+            rid = new_representatives[sid]
             s = self.species.get(sid)
             if s is None:
                 s = Species(sid, generation)

neat/stagnation.py

@@ -40,7 +40,11 @@ def update(self, species_set, generation):
         returns a list with stagnant species marked for removal.
         """
         species_data = []
-        for sid, s in species_set.species.items():
+        # Iterate species in a deterministic order (by species id) so that
+        # stagnation decisions are reproducible across runs and checkpoint
+        # restores, independent of dictionary insertion order.
+        for sid in sorted(species_set.species.keys()):
+            s = species_set.species[sid]
             if s.fitness_history:
                 prev_fitness = max(s.fitness_history)
             else: