Improve documentation and add main evolution simulation

[MatejGomboc-Claude-MCP]

Summary

This PR significantly improves the Evolution-Simulation project by adding comprehensive documentation, a main simulation program, example files, and new biological simulation features.

Changes Made

📚 Documentation

• Updated README.md with:
  • Project overview and features
  • Complete instruction set documentation including new biological instructions
  • Build instructions
  • Usage examples
  • Project structure guide
  • Detailed biological simulation mechanics

🚀 New Features

Main Evolution Simulation Program (evolution-sim/)

• Complete evolutionary algorithm implementation
• Organism class wrapping programs with fitness evaluation
• Tournament selection for parent selection
• Elitism to preserve best solutions
• Generation statistics tracking
• Command-line parameter support

🧬 Biological Simulation Features

• Energy System:

  • Organisms start with 100 energy units
  • Energy depletes over time (1 unit per step)
  • Death occurs when energy reaches 0
  • Food provides 30 energy units
  • Mating costs 20 energy units per parent

• New Instructions:

  • MATE_REQUEST: Request mating with another organism
  • MATE_ACCEPT: Accept a mating request from another organism
  • CONSUME_FOOD: Attempt to consume food for energy
  • ROCK_PAPER_SCISSORS: Conflict resolution mechanism

• Conflict Resolution System:

  • First: Rock-paper-scissors game
  • If tied: Higher energy wins
  • If still tied: Random selection (Bernoulli distribution)

• World Management:

  • Manages organisms, food, and interactions
  • Tracks mating requests and acceptances
  • Handles food consumption
  • Updates organism states and removes dead organisms

📝 Examples

• Created examples/ directory with sample programs:
  • simple_math.txt - Basic arithmetic operations
  • loop_example.txt - Loop control flow demonstration
  • condition_example.txt - Conditional execution
  • logic_operations.txt - Logical operations
  • biological_behavior.txt - Food consumption and mating
  • mating_sequence.txt - Mating request/acceptance flow
  • survival_strategy.txt - Complex survival behaviors
  • conflict_resolution.txt - Rock-paper-scissors example

🔧 Improvements

• Added comprehensive documentation to program.h using Doxygen-style comments
• Added missing s0.txt test file for test-save-load
• Updated CMakeLists.txt files to include new components
• Created biological_sim.h/cpp for biological simulation components

Implementation Details

Biological Components

• Organism: Extended with energy, age, and mating capabilities
• Food: Consumable items that restore energy
• World: Manages all entities and their interactions
• MatingRequest: Tracks mating proposals between organisms

Energy Dynamics

• Natural selection favors organisms with better energy management
• Energy acts as both a fitness metric and survival requirement
• Creates pressure for efficient food-finding behaviors

Genetic Inheritance

• Offspring inherit traits from parents
• Mutation rate controls program variation
• Population dynamics with extinction possibility

Testing

The changes maintain backward compatibility while adding new functionality. The existing test-save-load program now has the required test file and should run successfully.

Build Instructions

mkdir build
cd build
cmake ..
make

# Run the biological evolution simulation
./evolution-sim/evolution-sim [population_size] [mutation_rate] [generations] [food_spawn_rate]

# Example
./evolution-sim/evolution-sim 100 0.15 200 30

Future Enhancements

This PR lays the groundwork for further improvements:

• More sophisticated fitness functions based on behavior
• Crossover operations between parent programs
• Mutation operators for individual instructions
• Performance benchmarks
• GUI visualization of evolution progress
• Spatial environment with organism movement
• Predator-prey dynamics
• Resource competition strategies

Thank you for creating this interesting genetic programming framework! The biological features add a new dimension of realism to the evolution simulation, allowing for emergent behaviors related to survival, reproduction, and resource management.