Add disable_rule config flag for 75% crossover rule (#292)

Adds a `disable_rule` parameter to `[DefaultGenome]` so users can opt
into Stanley's reference NEAT C++ behavior alongside the current
neat-python semantics. Default remains `neat-python` (no behavior change
for existing configs).

- `neat-python`: when either parent has the gene disabled, replace the
  randomly-inherited `enabled` with a fresh Bernoulli(0.25) — 75%
  disabled regardless of how many parents had it disabled.
- `stanley`: random inherit, then 75% force-disable layered on top if
  either parent disabled — ~87.5% disabled with one parent disabled,
  100% disabled with both.

Threaded through `BaseGene.crossover()` as a keyword argument with a
backwards-compatible default so direct callers (tests, etc.) keep
working. Validated at config load.

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

Author: CodeReclaimers

neat/genes.py

@@ -72,10 +72,24 @@ def copy(self):
 
         return new_gene
 
-    def crossover(self, gene2):
-        """ Creates a new gene randomly inheriting attributes from its parents."""
+    def crossover(self, gene2, disable_rule='neat-python'):
+        """Create a new gene randomly inheriting attributes from its parents.
+
+        *disable_rule* selects how the NEAT paper's 75% disable rule is applied
+        to the ``enabled`` attribute (connection genes only):
+
+        - ``'neat-python'`` (default): if either parent has the gene disabled,
+          the randomly-inherited enabled value is REPLACED by a fresh
+          Bernoulli(0.25): 75% disabled, 25% enabled.
+        - ``'stanley'``: matches Stanley's reference NEAT C++ implementation.
+          The enabled value is first inherited from a random parent like every
+          other attribute, then if either parent has the gene disabled the
+          inherited value is force-disabled with probability 0.75 (otherwise
+          left alone). Yields ~87.5% disabled when exactly one parent is
+          disabled and 100% disabled when both parents are disabled.
+        """
         assert self.key == gene2.key
-        
+
         # For connection genes, verify innovation numbers match
         # (they should represent the same historical mutation)
         if hasattr(self, 'innovation'):
@@ -91,22 +105,29 @@ def crossover(self, gene2):
             new_gene = self.__class__(self.key, innovation=self.innovation)
         else:
             new_gene = self.__class__(self.key)
-        
+
         for a in self._gene_attributes:
             if random() > 0.5:
                 setattr(new_gene, a.name, getattr(self, a.name))
             else:
                 setattr(new_gene, a.name, getattr(gene2, a.name))
-        
+
         # 75% disable rule from NEAT paper (Stanley & Miikkulainen, 2002, p. 111):
         # "There was a 75% chance that an inherited gene was disabled if it was
         # disabled in either parent."
-        # This rule REPLACES the randomly-inherited enabled attribute when either
-        # parent has the gene disabled.
-        if hasattr(new_gene, 'enabled'):
-            if not self.enabled or not gene2.enabled:
+        if hasattr(new_gene, 'enabled') and (not self.enabled or not gene2.enabled):
+            if disable_rule == 'neat-python':
                 # Override whatever was randomly inherited: 75% disabled, 25% enabled.
                 new_gene.enabled = random() >= 0.75
+            elif disable_rule == 'stanley':
+                # Reference C++ behavior: 75% chance to force-disable the
+                # value that was just inherited above; otherwise leave it.
+                if random() < 0.75:
+                    new_gene.enabled = False
+            else:
+                raise ValueError(
+                    f"Unknown disable_rule {disable_rule!r}; "
+                    f"expected 'neat-python' or 'stanley'")
 
         return new_gene
 

neat/genome.py

@@ -17,6 +17,7 @@ class DefaultGenomeConfig:
     allowed_connectivity = ['unconnected', 'fs_neat_nohidden', 'fs_neat', 'fs_neat_hidden',
                             'full_nodirect', 'full', 'full_direct',
                             'partial_nodirect', 'partial', 'partial_direct']
+    allowed_disable_rules = ('neat-python', 'stanley')
 
     def __init__(self, params, section_name='DefaultGenome'):
         # Create full set of available activation functions.
@@ -40,7 +41,8 @@ def __init__(self, params, section_name='DefaultGenome'):
                         ConfigParameter('initial_connection', str, 'unconnected'),
                         ConfigParameter('compatibility_excess_coefficient', str, 'auto'),
                         ConfigParameter('compatibility_include_node_genes', bool, True),
-                        ConfigParameter('compatibility_enable_penalty', float, 1.0)]
+                        ConfigParameter('compatibility_enable_penalty', float, 1.0),
+                        ConfigParameter('disable_rule', str, 'neat-python')]
 
         # Gather configuration data from the gene classes.
         self.node_gene_type = params['node_gene_type']
@@ -116,6 +118,22 @@ def __init__(self, params, section_name='DefaultGenome'):
             error_string = f"Invalid structural_mutation_surer {self.structural_mutation_surer!r}"
             raise RuntimeError(error_string)
 
+        # Verify disable_rule is valid. Two interpretations of the NEAT paper's
+        # 75% disable rule are supported:
+        #   'neat-python' (default): if either parent has the gene disabled, a
+        #       fresh Bernoulli(0.25) replaces the randomly-inherited enabled
+        #       value -> 75% disabled / 25% enabled regardless of how many
+        #       parents had it disabled.
+        #   'stanley': the original NEAT C++ behavior. After randomly inheriting
+        #       the enabled attribute from a parent, if either parent has the
+        #       gene disabled, force-disable with probability 0.75; otherwise
+        #       keep the inherited value. Yields ~87.5% disabled when exactly
+        #       one parent is disabled and 100% disabled when both are.
+        if self.disable_rule not in self.allowed_disable_rules:
+            raise RuntimeError(
+                f"Invalid disable_rule {self.disable_rule!r}; "
+                f"expected one of {self.allowed_disable_rules}")
+
         self.node_indexer = None
 
         # Innovation tracker will be set by Population/Reproduction
@@ -347,7 +365,7 @@ def configure_crossover(self, genome1, genome2, config, fitness_criterion=None):
                         continue
                     self.connections[new_gene.key] = new_gene
                 else:
-                    new_gene = cg1.crossover(cg2)
+                    new_gene = cg1.crossover(cg2, disable_rule=config.disable_rule)
                     # For feed-forward networks, check if this connection would create a cycle
                     if config.feed_forward and creates_cycle(list(self.connections), new_gene.key):
                         continue
@@ -373,7 +391,9 @@ def configure_crossover(self, genome1, genome2, config, fitness_criterion=None):
                 self.nodes[key] = ng1.copy()
             else:
                 # Homologous gene: combine genes from both parents.
-                self.nodes[key] = ng1.crossover(ng2)
+                # Node genes have no ``enabled`` attribute, so the disable rule
+                # has no effect; pass it through for consistency.
+                self.nodes[key] = ng1.crossover(ng2, disable_rule=config.disable_rule)
 
     def mutate(self, config):
         """ Mutates this genome. """

tests/test_disable_rule.py

@@ -243,5 +243,106 @@ def test_mathematical_model_accuracy(self):
                               msg=f"Observed {observed_rate:.4f} should match model {expected_rate}")
 
 
+class TestStanleyDisableRule(unittest.TestCase):
+    """Tests for the 'stanley' disable_rule (reference C++ behavior).
+
+    Under the stanley rule, the enabled attribute is first randomly inherited
+    from a parent like every other attribute, then if either parent has the
+    gene disabled a 75% force-disable is layered on top. Expected rates:
+
+    - both disabled: 100% disabled (inherited value is always False; force-disable is a no-op)
+    - one disabled: 87.5% disabled (= 0.5 + 0.5 * 0.75)
+    - both enabled: 0% disabled (rule condition never triggers)
+    """
+
+    def _make_gene(self, weight, enabled, innovation=1):
+        g = DefaultConnectionGene((0, 1), innovation=innovation)
+        g.weight = weight
+        g.enabled = enabled
+        return g
+
+    def test_both_parents_disabled_is_always_disabled(self):
+        g1 = self._make_gene(1.0, False)
+        g2 = self._make_gene(2.0, False)
+        for _ in range(1000):
+            child = g1.crossover(g2, disable_rule='stanley')
+            self.assertFalse(child.enabled,
+                             "stanley rule: both-disabled parents must always produce disabled child")
+
+    def test_one_parent_disabled_rate_is_87_5_percent(self):
+        g1 = self._make_gene(1.0, False)
+        g2 = self._make_gene(2.0, True)
+        trials = 10000
+        disabled = sum(1 for _ in range(trials)
+                       if not g1.crossover(g2, disable_rule='stanley').enabled)
+        rate = disabled / trials
+        self.assertAlmostEqual(rate, 0.875, delta=0.02,
+                               msg=f"stanley rule: expected ~87.5% disabled, got {rate:.3f}")
+
+    def test_one_parent_disabled_rate_is_symmetric(self):
+        g_disabled = self._make_gene(1.0, False)
+        g_enabled = self._make_gene(2.0, True)
+        trials = 5000
+        r1 = sum(1 for _ in range(trials)
+                 if not g_disabled.crossover(g_enabled, disable_rule='stanley').enabled) / trials
+        r2 = sum(1 for _ in range(trials)
+                 if not g_enabled.crossover(g_disabled, disable_rule='stanley').enabled) / trials
+        self.assertAlmostEqual(r1, r2, delta=0.04,
+                               msg=f"rates should be symmetric: {r1:.3f} vs {r2:.3f}")
+        self.assertAlmostEqual(r1, 0.875, delta=0.03)
+
+    def test_both_parents_enabled_is_always_enabled(self):
+        g1 = self._make_gene(1.0, True)
+        g2 = self._make_gene(2.0, True)
+        for _ in range(1000):
+            child = g1.crossover(g2, disable_rule='stanley')
+            self.assertTrue(child.enabled,
+                            "stanley rule: both-enabled parents must always produce enabled child")
+
+    def test_unknown_disable_rule_raises(self):
+        g1 = self._make_gene(1.0, False)
+        g2 = self._make_gene(2.0, True)
+        with self.assertRaises(ValueError):
+            g1.crossover(g2, disable_rule='bogus')
+
+
+class TestDisableRuleConfigFlag(unittest.TestCase):
+    """Tests for the ``disable_rule`` config flag in [DefaultGenome]."""
+
+    def _load_config(self, override=None):
+        """Load the standard test config, optionally injecting an override line
+        for the ``disable_rule`` parameter."""
+        local_dir = os.path.dirname(__file__)
+        src_path = os.path.join(local_dir, 'test_configuration')
+        with open(src_path) as f:
+            text = f.read()
+        if override is not None:
+            # Inject the override into the [DefaultGenome] section header.
+            text = text.replace('[DefaultGenome]',
+                                f'[DefaultGenome]\ndisable_rule = {override}')
+        import tempfile
+        with tempfile.NamedTemporaryFile('w', suffix='.cfg', delete=False) as tmp:
+            tmp.write(text)
+            path = tmp.name
+        try:
+            return neat.Config(neat.DefaultGenome, neat.DefaultReproduction,
+                               neat.DefaultSpeciesSet, neat.DefaultStagnation,
+                               path)
+        finally:
+            os.unlink(path)
+
+    def test_default_is_neat_python(self):
+        cfg = self._load_config()
+        self.assertEqual(cfg.genome_config.disable_rule, 'neat-python')
+
+    def test_stanley_value_accepted(self):
+        cfg = self._load_config(override='stanley')
+        self.assertEqual(cfg.genome_config.disable_rule, 'stanley')
+
+    def test_invalid_value_rejected(self):
+        with self.assertRaises(RuntimeError):
+            self._load_config(override='bogus')
+
+
 if __name__ == '__main__':
     unittest.main()