macula_neuroevolution

# Changelog

All notable changes to macula-neuroevolution will be documented in this file.

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]

### Planned
- Wire L0 TWEANN evolution into neuroevolution_server
- Integration tests for cross-silo communication

---

## [0.13.0] - 2025-12-11

### Summary
**Liquid Conglomerate v2 Release** - Complete hierarchical meta-learning architecture with 3 specialized silos (Resource, Task, Distribution), L1/L2 controllers, and cross-silo communication.

### Added

#### LC v2 Architecture
- **lc_supervisor.erl** - Supervises all LC v2 child processes
- **lc_cross_silo.erl** - Signal routing between silos with validation and decay
- **lc_reward.erl** - Cooperative reward computation for all silos
- **lc_l1_controller.erl** - Generic L1 hyperparameter tuning
- **lc_l2_controller.erl** - Strategic meta-tuning with slow exploration

#### Silo Morphologies (TWEANN Sensor/Actuator Definitions)
- **resource_l0_morphology.erl** - Resource silo (13 sensors, 8 actuators)
- **task_l0_morphology.erl** - Task silo (16 sensors, 12 actuators)
- **distribution_l0_morphology.erl** - Distribution silo (14 sensors, 10 actuators)

#### Sensor & Actuator Implementations
- **resource_l0_sensors.erl** - System metrics collection
- **resource_l0_actuators.erl** - Resource control application
- **task_l0_sensors.erl** - Evolution statistics collection
- **task_l0_actuators.erl** - Evolution parameter application
- **distribution_l0_sensors.erl** - Network metrics collection
- **distribution_l0_actuators.erl** - Distribution control application

#### Unit Tests (108 new tests)
- **test/lc_morphology_tests.erl** - 43 tests for morphology modules
- **test/lc_reward_tests.erl** - 34 tests for reward computation
- **test/lc_l1_controller_tests.erl** - 15 tests for L1 controller
- **test/lc_l2_controller_tests.erl** - 16 tests for L2 controller

#### Documentation
- **guides/cooperative-silos.md** - Cross-silo communication guide
- **guides/assets/lc_architecture.svg** - Architecture overview diagram
- **guides/assets/lc_hierarchical_learning.svg** - Hierarchical learning diagram
- **guides/assets/lc_cross_silo_signals.svg** - Signal routing diagram
- **guides/assets/lc_silo_tweann_io.svg** - L0 TWEANN sensors/actuators diagram
- **guides/assets/lc_silo_interactions.svg** - Detailed cross-silo interaction flow diagram
- **guides/assets/lc_feedback_loop.svg** - Feedback loop between Resource and Task silos
- Updated **guides/meta-controller.md** with implementation roadmap

### Changed
- Updated implementation roadmap (Phases 3-6 complete)
- Enhanced LC v2 documentation with cooperative reward signals

### Theoretical Foundation
- Multi-timescale separation: Distribution (τ=1), Resource (τ=5), Task (τ=50)
- Hierarchical control: L0 (safety), L1 (feedback), L2 (feedforward)
- Graceful degradation: L2 failure → L1 fallback → L0 safety

### Test Results
- 326 tests passing (108 new LC v2 tests)
- Dialyzer clean
- All documentation links validated

---

## [0.12.1] - 2025-12-07

### Summary
**Safety & Dependency Update** - MAP-Elites grid validation and macula-tweann 0.13.0 compatibility.

### Changed
- **rebar.config**: Updated macula_tweann dependency from ~> 0.12.0 to ~> 0.13.0

### Fixed
- **map_elites_strategy.erl**: Added grid size validation to prevent unbounded memory growth
  - Maximum 10,000 cells enforced (e.g., 10 bins × 4 dimensions, or 100 bins × 2 dimensions)
  - Descriptive error with hint when configuration exceeds limit
  - Prevents potential OOM from high-dimensional behavior spaces

### Test Results
- 218 tests passing
- Dialyzer: 35 pre-existing warnings (unrelated to this release)

---

## [0.12.0] - 2025-12-01

### Summary
**Evolution Strategies & Meta-Learning Release** - Multiple evolution strategies with LTC meta-controller.

### Added

#### Evolution Strategies
- **generational_strategy.erl** - Classic generational GA
- **steady_state_strategy.erl** - Continuous replacement with age tracking
- **novelty_strategy.erl** - Novelty search with behavior archive
- **map_elites_strategy.erl** - Quality-Diversity algorithm with behavior grid
- **island_strategy.erl** - Island model with migration topology

#### Meta-Learning
- **meta_controller.erl** - LTC-based hyperparameter controller
- **meta_trainer.erl** - Advantage estimation and gradient computation
- **meta_reward.erl** - Multi-component reward calculation

#### Core Infrastructure
- **neuroevolution_server.erl** - Main gen_server for training orchestration
- **neuroevolution_events.erl** - Event system for training notifications
- **neuroevolution_selection.erl** - Selection operators (tournament, roulette, top-N)
- **neuroevolution_genetic.erl** - Crossover and mutation operators
- **neuroevolution_speciation.erl** - NEAT-style speciation support
- **neuroevolution_stats.erl** - Population statistics

#### Documentation
- Comprehensive guides for all features
- Architecture overview with diagrams
- LTC meta-controller explanation
- Liquid Conglomerate vision document

---

## [0.11.0] - 2025-11-15

### Summary
Initial public release with core neuroevolution functionality.

### Added
- Basic population management
- Parallel fitness evaluation
- Weight mutation and crossover
- Event callback system
- Integration with macula_tweann

---

[Unreleased]: https://github.com/macula-io/macula-neuroevolution/compare/v0.13.0...HEAD
[0.13.0]: https://github.com/macula-io/macula-neuroevolution/compare/v0.12.1...v0.13.0
[0.12.1]: https://github.com/macula-io/macula-neuroevolution/compare/v0.12.0...v0.12.1
[0.12.0]: https://github.com/macula-io/macula-neuroevolution/compare/v0.11.0...v0.12.0
[0.11.0]: https://github.com/macula-io/macula-neuroevolution/releases/tag/v0.11.0