Reproducibility and documentation enhancements.

Author: CodeReclaimers

CHANGELOG.md

@@ -6,6 +6,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [Unreleased]
+
+### Added
+- **Reproducibility Support**: Evolution can now be made deterministic by setting a random seed
+  - Optional `seed` parameter in `[NEAT]` config section
+  - Optional `seed` parameter in `Population.__init__()`
+  - Optional `seed` parameter in `ParallelEvaluator.__init__()` for reproducible parallel evaluation
+  - Per-genome deterministic seeding in parallel mode (seed + genome.key)
+  - Comprehensive documentation in `docs/reproducibility.rst`
+  - Complete test coverage in `tests/test_reproducibility.py` (9 tests)
+  - **Fully backward compatible**: Existing code works without changes
+  - Seed parameter controls Python's `random` module
+  - Checkpoint system already preserved random state (unchanged)
+  - All changes are fully backward compatible
+
 ## [1.0.0] - 2025-01-09
 
 ### Added

README.md

@@ -14,6 +14,15 @@ For further information regarding general concepts and theory, please see the [p
 `neat-python` is licensed under the [3-clause BSD license](https://opensource.org/licenses/BSD-3-Clause).  It is
 currently only supported on Python 3.8 through 3.14, and pypy3.
 
+## Features ##
+
+* Pure Python implementation with no dependencies beyond the standard library
+* Supports Python 3.8-3.14 and PyPy 3
+* **Reproducible evolution** - Set random seeds for deterministic, repeatable experiments
+* Parallel fitness evaluation using multiprocessing
+* Network export to JSON format for interoperability
+* Comprehensive documentation and examples
+
 ## Getting Started ##
 
 If you want to try neat-python, please check out the repository, start playing with the examples (`examples/xor` is

docs/conf.py

@@ -40,7 +40,10 @@
     'sphinx.ext.napoleon',  # Google/NumPy docstring support
   # note: the below does not actually require (at least the Python) graphviz
   # package to be installed
-    'sphinx.ext.inheritance_diagram', 
+    'sphinx.ext.inheritance_diagram',
+    # Enhanced user experience
+    'sphinx_copybutton',  # Adds copy button to code blocks
+    'sphinx_design',      # Adds cards, tabs, badges for enhanced formatting
 ]
 
 extlinks = {'pytypes': ('https://docs.python.org/3/library/stdtypes.html#%s',
@@ -133,6 +136,12 @@
 # Provide links to python3 documentation
 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
 
+# -- Options for sphinx_copybutton ----------------------------------------
+
+# Remove prompts when copying code (e.g., >>>, $, In [1]:)
+copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: |Out\[\d*\]: "
+copybutton_prompt_is_regexp = True
+
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

docs/config_file.rst

@@ -75,6 +75,36 @@ itself.  This section is always required, and is handled by the `Config` class i
     If this evaluates to ``True``, when all species simultaneously become extinct due to stagnation, a new random
     population will be created. If ``False``, a `CompleteExtinctionException` will be thrown.
 
+.. _seed-label:
+
+.. index:: ! seed
+.. index:: reproducibility
+.. index:: random
+
+* *seed*
+    Optional random seed for reproducible evolution. If specified, sets the seed for Python's ``random`` module,
+    making evolution deterministic. If omitted or set to ``None``, behavior is non-deterministic (different results
+    each run). **This parameter is optional and defaults to None.**
+    
+    Example usage:
+    
+    .. code-block:: ini
+    
+       [NEAT]
+       pop_size = 150
+       seed = 42  # Enable reproducibility
+    
+    The seed can also be set or overridden programmatically:
+    
+    .. code-block:: python
+    
+       pop = neat.Population(config, seed=42)
+    
+    For detailed information about reproducibility, including parallel evaluation and best practices,
+    see :ref:`reproducibility-label`.
+    
+    .. versionadded:: 1.1
+
 .. index:: stagnation
 .. index:: DefaultStagnation
 

docs/index.rst

@@ -57,11 +57,12 @@ Contents:
    :caption: User Guides
 
    config_file
+   reproducibility
    customization
-   cookbook
    activation
    ctrnn
    network_export
+   network_export
 
 .. toctree::
    :maxdepth: 2