Add per-node time constants to CTRNN, bump version to 2.0.0

CodeReclaimers · claude · CodeReclaimers · commit 8fe2d5b9e2e2 · 2026-03-02T11:24:09.000-05:00
time_constant is now an evolvable per-node attribute of DefaultNodeGene
instead of a fixed parameter passed to CTRNN.create(). This matches the
Julia NeatEvolution implementation and removes the dominant bottleneck
identified in the Lorenz CTRNN experiment.

Breaking change: CTRNN.create(genome, config, time_constant) is now
CTRNN.create(genome, config). Config defaults policy relaxed so that
parameters with non-None defaults are used silently when missing from
config, allowing feedforward/recurrent configs to work unchanged.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/docs/module_summaries.rst b/docs/module_summaries.rst
@@ -653,16 +653,19 @@ ctrnn
       .. versionchanged:: 0.92
         Exception changed to more-specific RuntimeError.
 
-    .. py:staticmethod:: create(genome, config, time_constant)
+    .. py:staticmethod:: create(genome, config)
 
       Receives a genome and returns its phenotype (a :py:class:`CTRNN` with :py:class:`CTRNNNodeEval` :term:`nodes <node>`).
+      Each node's time constant is read from the genome's node gene ``time_constant`` attribute.
 
       :param genome: A :py:class:`genome.DefaultGenome` instance.
       :type genome: :datamodel:`instance <index-48>`
       :param config: A :py:class:`config.Config` instance.
       :type config: :datamodel:`instance <index-48>`
-      :param time_constant: Used for the :py:class:`CTRNNNodeEval` initializations.
-      :type time_constant: :pytypes:`float <typesnumeric>`
+
+      .. versionchanged:: 2.0.0
+        The ``time_constant`` parameter was removed. Time constants are now per-node
+        attributes evolved as part of the genome.
 
 
 .. py:module:: parallel
diff --git a/docs/network_export.rst b/docs/network_export.rst
@@ -332,8 +332,8 @@ Export Different Network Types
    rnn = neat.nn.RecurrentNetwork.create(genome, config)
    export_network_json(rnn, 'recurrent.json')
    
-   # CTRNN
-   ctrnn = neat.ctrnn.CTRNN.create(genome, config, time_constant=1.0)
+   # CTRNN (time constants are per-node, read from genome)
+   ctrnn = neat.ctrnn.CTRNN.create(genome, config)
    export_network_json(ctrnn, 'ctrnn.json')
    
    # IZNN (requires IZGenome)
diff --git a/examples/lorenz-ctrnn/README.md b/examples/lorenz-ctrnn/README.md
@@ -51,11 +51,9 @@ Each CTRNN receives the normalized current state as input and predicts the norma
 
 ## Differences from the Julia version
 
-The Julia NeatEvolution CTRNN implementation evolves **per-node time constants** as part of the genome, with each node having its own time constant in the range [0.01, 5.0]. This allows different nodes to operate at different timescales -- some responding quickly (small tau) and others integrating slowly (large tau).
+neat-python now evolves **per-node time constants** as part of the genome, matching the Julia NeatEvolution implementation. Each node has its own time constant (tau) in the range [0.01, 5.0], allowing different nodes to operate at different timescales.
 
-neat-python's CTRNN implementation uses a **single fixed time constant** for all nodes, set at network creation time. This example uses tau=1.0 (matching the Julia version's initialization mean). This is a genuine capability difference: the Python CTRNN cannot learn different timescales for different nodes.
-
-Additionally, the Julia implementation separates disjoint and excess gene coefficients for the genetic distance calculation, while neat-python combines them into a single `compatibility_disjoint_coefficient`.
+The Julia implementation separates disjoint and excess gene coefficients for the genetic distance calculation, while neat-python combines them into a single `compatibility_disjoint_coefficient`.
 
 ## Visualization (optional)
 
@@ -73,7 +71,7 @@ pip install matplotlib
 - **3 or 6 inputs** (with `--mode products`), **3 or 1 outputs** (with `--z-only`)
 - **No initial hidden nodes** -- NEAT discovers the topology
 - **feed_forward = False** -- required for CTRNN recurrence
-- **time_constant = 1.0** -- fixed for all nodes (see differences above)
+- **per-node time constants** -- evolved, initialized from N(1.0, 0.5), range [0.01, 5.0]
 - **bias/weight range [-5, 5]** -- narrower bounds for tanh activation
 - **max_stagnation = 30** -- patient stagnation threshold for a harder task
 - **10x subsampling** -- ensures per-step state change is large enough that networks must learn dynamics, not just copy input
diff --git a/examples/lorenz-ctrnn/config-ctrnn b/examples/lorenz-ctrnn/config-ctrnn
@@ -4,10 +4,8 @@
 # Output: predicted normalized (x, y, z) at time t+1
 #
 # Ported from the Julia NeatEvolution lorenz_ctrnn example.
-# Key difference: neat-python's CTRNN uses a single fixed time constant for
-# all nodes (set in the script), whereas the Julia version evolves per-node
-# time constants. The time_constant_* parameters from the Julia config are
-# therefore omitted here.
+# Per-node time constants are evolved as part of the genome, matching the
+# Julia implementation.
 
 [NEAT]
 fitness_criterion     = max
@@ -65,6 +63,16 @@ response_mutate_power   = 0.0
 response_mutate_rate    = 0.0
 response_replace_rate   = 0.0
 
+# Per-node time constants (matching Julia NeatEvolution config)
+time_constant_init_mean      = 1.0
+time_constant_init_stdev     = 0.5
+time_constant_init_type      = gaussian
+time_constant_max_value      = 5.0
+time_constant_min_value      = 0.01
+time_constant_mutate_power   = 0.1
+time_constant_mutate_rate    = 0.5
+time_constant_replace_rate   = 0.1
+
 # Weight parameters
 weight_init_mean        = 0.0
 weight_init_stdev       = 2.0
diff --git a/examples/lorenz-ctrnn/evolve_lorenz_ctrnn.py b/examples/lorenz-ctrnn/evolve_lorenz_ctrnn.py
@@ -46,11 +46,6 @@
 N_GENERATIONS = 300
 PENALTY_FITNESS = -10.0
 
-# neat-python's CTRNN uses a single fixed time constant for all nodes.
-# The Julia version evolves per-node time constants (mean=1.0, range [0.01, 5.0]).
-# We use the Julia mean as the fixed value.
-TIME_CONSTANT = 1.0
-
 # ---------------------------------------------------------------------------
 # Module-level globals for parallel evaluation
 # Set by main() before the ParallelEvaluator pool is created so that forked
@@ -208,7 +203,7 @@ def eval_genome(genome, config):
 
     Returns negative mean squared error (evolution maximizes toward zero).
     """
-    net = neat.ctrnn.CTRNN.create(genome, config, TIME_CONSTANT)
+    net = neat.ctrnn.CTRNN.create(genome, config)
     net.reset()
 
     n_steps = len(_train_inputs)
@@ -238,7 +233,7 @@ def evaluate_on_test(winner, config, test_input, target_rows):
     Returns (mse, predictions) where predictions is a list of output vectors
     in normalized space.
     """
-    net = neat.ctrnn.CTRNN.create(winner, config, TIME_CONSTANT)
+    net = neat.ctrnn.CTRNN.create(winner, config)
     net.reset()
 
     n_steps = len(test_input) - 1
@@ -452,7 +447,7 @@ def main():
     print(f'After subsampling: {TRAIN_STEPS // SUBSAMPLE} train points, '
           f'{TEST_STEPS // SUBSAMPLE} test points')
     print(f'Evolution:  {N_GENERATIONS} generations, pop_size=150')
-    print(f'CTRNN:      time_constant={TIME_CONSTANT} (fixed, all nodes)')
+    print(f'CTRNN:      per-node time constants (evolved)')
     print(f'Workers:    {num_workers}')
     print()
 
diff --git a/examples/single-pole-balancing/config-ctrnn b/examples/single-pole-balancing/config-ctrnn
@@ -39,6 +39,16 @@ response_mutate_power   = 0.0
 response_max_value      = 30.0
 response_min_value      = -30.0
 
+# Per-node time constants (preserves original fixed value as init_mean)
+time_constant_init_mean      = 0.01
+time_constant_init_stdev     = 0.0
+time_constant_init_type      = gaussian
+time_constant_max_value      = 1.0
+time_constant_min_value      = 0.001
+time_constant_mutate_power   = 0.005
+time_constant_mutate_rate    = 0.3
+time_constant_replace_rate   = 0.05
+
 weight_max_value        = 30
 weight_min_value        = -30
 weight_init_mean        = 0.0
diff --git a/examples/single-pole-balancing/evolve-ctrnn.py b/examples/single-pole-balancing/evolve-ctrnn.py
@@ -12,12 +12,11 @@
 
 runs_per_net = 5
 simulation_seconds = 60.0
-time_const = cart_pole.CartPole.time_step
 
 
 # Use the CTRNN network phenotype and the discrete actuator force function.
 def eval_genome(genome, config):
-    net = neat.ctrnn.CTRNN.create(genome, config, time_const)
+    net = neat.ctrnn.CTRNN.create(genome, config)
 
     fitnesses = []
     for runs in range(runs_per_net):
@@ -28,7 +27,7 @@ def eval_genome(genome, config):
         fitness = 0.0
         while sim.t < simulation_seconds:
             inputs = sim.get_scaled_state()
-            action = net.advance(inputs, time_const, time_const)
+            action = net.advance(inputs, sim.time_step, sim.time_step)
 
             # Apply action to the simulated cart-pole
             force = cart_pole.discrete_actuator_force(action)
diff --git a/examples/single-pole-balancing/test-ctrnn.py b/examples/single-pole-balancing/test-ctrnn.py
@@ -26,7 +26,7 @@
 
 sim = CartPole()
 
-net = neat.ctrnn.CTRNN.create(c, config, sim.time_step)
+net = neat.ctrnn.CTRNN.create(c, config)
 
 print()
 print("Initial conditions:")
diff --git a/neat/__init__.py b/neat/__init__.py
@@ -1,6 +1,6 @@
 """A NEAT (NeuroEvolution of Augmenting Topologies) implementation"""
 
-__version__ = '1.1.0'
+__version__ = '2.0.0'
 
 import neat.nn as nn
 import neat.ctrnn as ctrnn
diff --git a/neat/config.py b/neat/config.py
@@ -74,13 +74,7 @@ def interpret(self, config_dict: Mapping[str, Any], section_name: Optional[str]
                 else:
                     raise RuntimeError(f"Missing required configuration item: '{self.name}'")
             else:
-                # For v1.0: Require all parameters to be explicitly specified
-                section_info = f" in [{section_name}] section" if section_name else ""
-                raise RuntimeError(
-                    f"Missing required configuration item{section_info}: '{self.name}'\n"
-                    f"This parameter must be explicitly specified in your configuration file.\n"
-                    f"Suggested value: {self.name} = {self.default}"
-                )
+                return self.default
 
         try:
             if str == self.value_type:
diff --git a/neat/ctrnn/__init__.py b/neat/ctrnn/__init__.py
@@ -86,7 +86,7 @@ def advance(self, inputs, advance_time, time_step=None):
         return [ovalues[i] for i in self.output_nodes]
 
     @staticmethod
-    def create(genome, config, time_constant):
+    def create(genome, config):
         """ Receives a genome and returns its phenotype (a CTRNN). """
         genome_config = config.genome_config
         required = required_for_output(genome_config.input_keys, genome_config.output_keys, genome.connections)
@@ -111,7 +111,7 @@ def create(genome, config, time_constant):
             node = genome.nodes[node_key]
             activation_function = genome_config.activation_defs.get(node.activation)
             aggregation_function = genome_config.aggregation_function_defs.get(node.aggregation)
-            node_evals[node_key] = CTRNNNodeEval(time_constant,
+            node_evals[node_key] = CTRNNNodeEval(node.time_constant,
                                                  activation_function,
                                                  aggregation_function,
                                                  node.bias,
diff --git a/neat/genes.py b/neat/genes.py
@@ -116,14 +116,20 @@ class DefaultNodeGene(BaseGene):
     _gene_attributes = [FloatAttribute('bias'),
                         FloatAttribute('response'),
                         StringAttribute('activation', options=''),
-                        StringAttribute('aggregation', options='')]
+                        StringAttribute('aggregation', options=''),
+                        FloatAttribute('time_constant',
+                                       init_mean=1.0, init_stdev=0.0,
+                                       replace_rate=0.0, mutate_rate=0.0,
+                                       mutate_power=0.0,
+                                       max_value=10.0, min_value=0.01)]
 
     def __init__(self, key):
         assert isinstance(key, int), f"DefaultNodeGene key must be an int, not {key!r}"
         BaseGene.__init__(self, key)
 
     def distance(self, other, config):
         d = abs(self.bias - other.bias) + abs(self.response - other.response)
+        d += abs(self.time_constant - other.time_constant)
         if self.activation != other.activation:
             d += 1.0
         if self.aggregation != other.aggregation:
diff --git a/progress-20260302.md b/progress-20260302.md
@@ -39,5 +39,62 @@ Ran the same protocol as the Julia experiment: 3 input modes (base, products, pr
 **Intermittent OverflowError:** ~1 in 9 product-agg runs crash with float64 overflow in neat-python's variance calculation when genomes with extremely poor fitness cause `(v - mean)^2` to overflow. Pre-existing neat-python issue, not introduced by this port.
 
 ### Next Steps
-- Consider adding per-node time constant support to neat-python's CTRNN (separate effort)
+- ~~Consider adding per-node time constant support to neat-python's CTRNN (separate effort)~~ Done — see below.
 - The product-agg failure result extends the Julia findings and is worth investigating further
+
+---
+
+## Per-node time constants for CTRNN + Version 2.0.0
+
+### Summary
+Added `time_constant` as an evolvable per-node attribute of `DefaultNodeGene`, removed the fixed `time_constant` parameter from `CTRNN.create()`, and bumped the version to 2.0.0. This was the dominant bottleneck identified in the Lorenz CTRNN experiment — the fixed time constant degraded correlation by ~2x and MSE by 2-3x compared to the Julia NeatEvolution implementation, which evolves per-node time constants.
+
+### Files Modified
+
+**Core library (4 files):**
+- `neat/config.py` — Relaxed `ConfigParameter.interpret()` to return `self.default` when a parameter has a non-None default but is missing from config, instead of raising RuntimeError. This allows the new `time_constant` attribute to have inert defaults that are used silently by feedforward/recurrent configs.
+- `neat/genes.py` — Added `FloatAttribute('time_constant', init_mean=1.0, init_stdev=0.0, mutate_rate=0.0, ...)` to `DefaultNodeGene._gene_attributes`; updated `distance()` to include `abs(self.time_constant - other.time_constant)`.
+- `neat/ctrnn/__init__.py` — `CTRNN.create(genome, config)` signature changed (removed `time_constant` param); now reads `node.time_constant` from each genome node gene.
+- `neat/__init__.py` — Version bumped to `'2.0.0'`.
+
+**Build config:** `pyproject.toml` — version bumped to `"2.0.0"`.
+
+**Tests (4 files):**
+- `tests/test_ctrnn.py` — Set `time_constant` on hand-built nodes, removed third arg from `create()`, assertions now compare against `node.time_constant`.
+- `tests/test_simple_run.py` — Removed third arg from 2 `CTRNN.create()` calls.
+- `tests/test_export.py` — Removed `time_constant=1.0` kwarg from `CTRNN.create()`.
+- `tests/test_genes.py` — Added `time_constant` to all hand-constructed `DefaultNodeGene` instances (4 tests).
+
+**Examples (6 files):**
+- `examples/lorenz-ctrnn/config-ctrnn` — Added `time_constant_*` params matching Julia config (init_mean=1.0, init_stdev=0.5, range [0.01, 5.0], mutate_rate=0.5).
+- `examples/lorenz-ctrnn/evolve_lorenz_ctrnn.py` — Removed `TIME_CONSTANT` constant and all references, updated `CTRNN.create()` calls.
+- `examples/lorenz-ctrnn/README.md` — Updated to reflect per-node time constants.
+- `examples/single-pole-balancing/config-ctrnn` — Added `time_constant_*` params (init_mean=0.01, preserving original fixed value).
+- `examples/single-pole-balancing/evolve-ctrnn.py` — Removed `time_const` variable, updated `create()` and `advance()` calls.
+- `examples/single-pole-balancing/test-ctrnn.py` — Removed third arg from `CTRNN.create()`.
+
+**Documentation (2 files):**
+- `docs/module_summaries.rst` — Updated `CTRNN.create()` signature and added `versionchanged:: 2.0.0` note.
+- `docs/network_export.rst` — Updated CTRNN example code.
+
+### Key Design Decisions
+
+**Config defaults relaxation (v1.0 → v2.0 policy change):** Adding `FloatAttribute('time_constant')` to `DefaultNodeGene` means all ~35 config files with `[DefaultGenome]` would need 8 new parameters — even feedforward configs that never use the time constant. Instead, `ConfigParameter.interpret()` was changed to return `self.default` silently when a parameter has a non-None default but is missing from config. Safety analysis: all existing `FloatAttribute._config_items` have `default=None` (bias, response, weight params), so this change has zero visible effect on existing configs. Only the new `time_constant` FloatAttribute and `init_type` (default='gaussian') have non-None defaults, and `init_type` is already present in all configs. Alternative rejected: making time_constant optional with a sentinel value — this would have required special-casing in `BaseGene.init_attributes()` and `mutate()`.
+
+**Inert defaults for feedforward/recurrent:** The time_constant attribute defaults are specifically chosen so it has no effect when not configured: `init_stdev=0.0` means all nodes get exactly `init_mean=1.0`, `mutate_rate=0.0` means it never changes, and equal time constants contribute zero to genetic distance. This means feedforward and recurrent configs work identically to before without any changes.
+
+**Breaking API change (v2.0.0):** `CTRNN.create()` signature changed from `create(genome, config, time_constant)` to `create(genome, config)`. Any code calling with the old signature will get a clear `TypeError: create() takes 2 positional arguments but 3 were given`. This is the correct versioning: a breaking public API change warrants a major version bump.
+
+### Coverage Verification
+
+Coverage was checked before and after the change:
+- **Before (v1.1.0):** 96% total (2099 stmts, 87 miss)
+- **After (v2.0.0):** 96% total (2099 stmts, 84 miss) — 3 fewer misses
+- `neat/config.py` improved from 89% to 91% because the old multi-line error branch (dead code for non-None defaults) was replaced by a single `return self.default` that gets exercised.
+- No coverage dropped in any file.
+
+### Test Results
+510 passed, 3 skipped, 0 failures.
+
+### Next Steps
+- Run the Lorenz experiment protocol (Step 11 from the plan) with per-node time constants to measure the improvement over the fixed time constant baseline
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "neat-python"
-version = "1.1.0"
+version = "2.0.0"
 description = "A NEAT (NeuroEvolution of Augmenting Topologies) implementation"
 readme = "README.md"
 requires-python = ">=3.8"
diff --git a/tests/test_ctrnn.py b/tests/test_ctrnn.py
@@ -133,18 +133,21 @@ def test_ctrnn_create_from_genome_prunes_and_builds_expected_structure():
     node0.response = 1.0
     node0.activation = "sigmoid"
     node0.aggregation = "sum"
+    node0.time_constant = 0.01
 
     node1 = DefaultNodeGene(1)
     node1.bias = -0.2
     node1.response = 1.0
     node1.activation = "sigmoid"
     node1.aggregation = "sum"
+    node1.time_constant = 0.01
 
     node2 = DefaultNodeGene(2)
     node2.bias = 1.5
     node2.response = 1.0
     node2.activation = "sigmoid"
     node2.aggregation = "sum"
+    node2.time_constant = 0.01
 
     genome.nodes[0] = node0
     genome.nodes[1] = node1
@@ -164,8 +167,7 @@ def test_ctrnn_create_from_genome_prunes_and_builds_expected_structure():
     genome.connections[conn1_key] = conn1
     genome.connections[conn2_key] = conn2
 
-    time_constant = 0.01
-    net = neat.ctrnn.CTRNN.create(genome, config, time_constant)
+    net = neat.ctrnn.CTRNN.create(genome, config)
 
     genome_config = config.genome_config
 
@@ -177,15 +179,15 @@ def test_ctrnn_create_from_genome_prunes_and_builds_expected_structure():
     assert set(net.node_evals.keys()) == {0, 1}
 
     ne_hidden = net.node_evals[1]
-    assert ne_hidden.time_constant == time_constant
+    assert ne_hidden.time_constant == node1.time_constant
     assert ne_hidden.bias == node1.bias
     assert ne_hidden.response == node1.response
     assert ne_hidden.activation is genome_config.activation_defs.get(node1.activation)
     assert ne_hidden.aggregation is genome_config.aggregation_function_defs.get(node1.aggregation)
     assert ne_hidden.links == [(-1, 0.5)]
 
     ne_output = net.node_evals[0]
-    assert ne_output.time_constant == time_constant
+    assert ne_output.time_constant == node0.time_constant
     assert ne_output.bias == node0.bias
     assert ne_output.response == node0.response
     assert ne_output.activation is genome_config.activation_defs.get(node0.activation)
diff --git a/tests/test_export.py b/tests/test_export.py
@@ -88,7 +88,7 @@ def test_ctrnn_export():
     genome = create_simple_genome(config)
     
     # Create CTRNN
-    net = neat.ctrnn.CTRNN.create(genome, config, time_constant=1.0)
+    net = neat.ctrnn.CTRNN.create(genome, config)
     
     # Export to JSON
     json_str = export_network_json(net)
diff --git a/tests/test_genes.py b/tests/test_genes.py
diff --git a/tests/test_simple_run.py b/tests/test_simple_run.py
