{"id":31923517,"url":"https://github.com/ortanav2/thinkblue","last_synced_at":"2025-10-13T23:54:43.179Z","repository":{"id":312575569,"uuid":"1044479735","full_name":"ortanaV2/ThinkBlue","owner":"ortanaV2","description":"Transforming the complexity of marine ecosystems into a living laboratory - where environmental scenarios play out in minutes, revealing adaptation patterns and informing strategies to protect our oceans.","archived":false,"fork":false,"pushed_at":"2025-10-04T11:22:31.000Z","size":469,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-11T09:10:08.059Z","etag":null,"topics":["climate-change","coral","coral-reefs","digital-twin","fish","global-warming","ocean","python","reinforcement-learning","simulation"],"latest_commit_sha":null,"homepage":"https://bwki.asai.ac.at/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ortanaV2.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-25T18:42:38.000Z","updated_at":"2025-10-04T15:51:39.000Z","dependencies_parsed_at":"2025-08-31T17:30:08.875Z","dependency_job_id":"25ddbdb5-4714-4722-a4d3-eb45d624b495","html_url":"https://github.com/ortanaV2/ThinkBlue","commit_stats":null,"previous_names":["ortanav2/thinkingblue","ortanav2/thinkblue"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ortanaV2/ThinkBlue","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ortanaV2%2FThinkBlue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ortanaV2%2FThinkBlue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ortanaV2%2FThinkBlue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ortanaV2%2FThinkBlue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ortanaV2","download_url":"https://codeload.github.com/ortanaV2/ThinkBlue/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ortanaV2%2FThinkBlue/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279017193,"owners_count":26086017,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["climate-change","coral","coral-reefs","digital-twin","fish","global-warming","ocean","python","reinforcement-learning","simulation"],"created_at":"2025-10-13T23:54:41.788Z","updated_at":"2025-10-13T23:54:43.171Z","avatar_url":"https://github.com/ortanaV2.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg width=\"3840\" height=\"659\" alt=\"ThinkBlue\" src=\"https://github.com/user-attachments/assets/cdb42ab5-0391-411b-b910-5490537372b6\" /\u003e\n\n**Marine Ecosystem Simulation with Reinforcement Learning Agents**\n\nTransforming the complexity of marine ecosystems into a living laboratory - where environmental scenarios play out in minutes, revealing adaptation patterns and informing strategies to protect our oceans.\n\n\u003cimg width=\"1431\" height=\"577\" alt=\"thinkbluebanner2\" src=\"https://github.com/user-attachments/assets/99784377-ee13-45ee-b830-726641687e70\" /\u003e\n\n## Core Features\n\n### **Dynamic Ecosystem Simulation**\n- **20 Marine Plant Species**: Hard corals, soft corals, marine plants, and other organisms with realistic growth patterns\n- **13 Fish Species**: From small herbivores to apex predators, each with unique behavioral characteristics\n- **Plant Growth Dynamics**: Plants grow, spread, compete for resources, and respond to environmental conditions\n- **Oxygen Production**: Plants generate oxygen that creates environmental gradients affecting fish survival\n- **Nutrient Cycling**: Complete ecosystem with plant consumption, fish digestion, waste production, and decomposition\n\n### **Reinforcement Learning Fish Agents**\n- **Advanced Vision System**: 180° field of view vector that points to nearest plants \u0026 predators\n- **Neural Network Architecture**: 3-layer deep network (7→20→3) with Xavier initialization\n- **Intelligent Behavior**: Fish learn optimal foraging, predator avoidance, and oxygen management strategies\n- **Sophisticated Reward System**: Multi-component rewards based on nutrition quality, oxygen levels, movement efficiency, and survival\n\n### **Advanced Simulation Systems**\n- **Spatial Optimization**: Grid-based collision detection and spatial partitioning for performance\n- **Physics Engine**: Realistic underwater physics with drag forces, repulsion dynamics, and flow fields\n- **Environmental Layers**: Real-time oxygen and nutrition heatmaps with visual rendering\n- **Temperature Control**: Coral bleaching simulation with temperature-dependent ecosystem responses\n- **Statistics Monitoring**: Real-time ecosystem metrics with GUI controls for environmental parameters\n\n## Technical Architecture\n\n### **Hybrid C/Python Implementation**\n- **C Backend**: High-performance simulation core handling physics, rendering, and ecosystem dynamics\n- **Python Integration**: Reinforcement learning agents implemented in Python with C API integration\n- **Modular Design**: Separate systems for physics, rendering, plant growth, fish behavior, and environmental layers\n- **Configuration-Driven**: Organism properties defined in external configuration files for easy modification\n\n### **Neural Network System**\nThe fish use a sophisticated neural network architecture:\n\n**Input Layer (7 neurons):**\n- `target_vector_x`: X-component of direction to nearest food source\n- `target_vector_y`: Y-component of direction to nearest food source  \n- `oxygen_level`: Current oxygen level at fish position (0.0-1.0)\n- `target_distance`: Distance to nearest food source\n- `threat_vector_x`: X-component of direction to nearest predator\n- `threat_vector_y`: Y-component of direction to nearest predator\n- `danger_level`: Threat assessment of nearby predators\n\n**Hidden Layer (20 neurons):**\n- ReLU activation with Xavier/Glorot weight initialization\n- Biased toward exploration in early learning phases\n\n**Output Layer (3 neurons):**\n- `turn_direction`: Steering control (-1.0 to 1.0, left to right)\n- `movement_strength`: Speed control (0.0 to 1.0, stop to full speed)\n- `eat_command`: Feeding behavior (0.0 to 1.0, ignore to consume)\n\n**Learning Algorithm:**\n- Gradient-based learning with experience replay\n- Adaptive epsilon-greedy exploration (starts at 0.6, decays to 0.05)\n- Momentum-based action smoothing to prevent erratic movement\n- Parent-child neural network inheritance during reproduction\n\n### **Environmental Systems**\n\n**Plant Growth Simulation:**\n- Individual species have distinct growth probabilities and branching patterns\n- Plants compete for space and resources through nutrition depletion\n- Oxygen production varies by species and environmental conditions\n- Aging effects change plant appearance and productivity over time\n\n**Predator-Prey Dynamics:**\n- Herbivorous fish target plants using chemoreceptor sensing\n- Predatory fish hunt other fish using visual detection systems\n- Eating cooldowns prevent unrealistic feeding behavior\n- Corpse system provides nutrition sources after fish death\n\n**Flow Dynamics:**\n- Dynamic water current simulation affects fish movement and behavior\n- Flow fields create realistic underwater movement patterns with directional forces\n- Fish learn to use currents for efficient transportation and energy conservation\n- Flow strength varies spatially creating micro-environments within the ecosystem\n- Current patterns influence plant growth and particle distribution\n\n**Oxygen and Nutrition Layers:**\n- Plants produce oxygen in radius-based gradients\n- Fish consume oxygen based on activity and species metabolism  \n- Nutrition gradients guide fish toward food sources\n- Waste products from fish digestion fertilize plant growth\n\n## Installation and Setup\n\n### **System Requirements**\n- **MSYS2/MinGW64** development environment (Windows)\n- **SDL2** graphics library for rendering\n- **Python 3.12** with development headers for neural networks\n- **GCC compiler** with C99 standard support\n\n### **Environment Setup**\n\nThe Python environment must be configured correctly for the neural network system to function:\n\n```bash\n# Set environment variables (REQUIRED)\nexport PATH=\"/mingw64/bin:$PATH\"\nexport PYTHONHOME=/mingw64 \nexport PYTHONPATH=/mingw64/lib/python3.12\n```\n\n### **Installation Steps**\n\n1. **Install MSYS2/MinGW64** from https://www.msys2.org/\n\n2. **Install dependencies:**\n```bash\n# Install required packages\nmake install-deps\n\n# Or manually:\npacman -S --needed --noconfirm \\\n    mingw-w64-x86_64-SDL2 \\\n    mingw-w64-x86_64-python \\\n    mingw-w64-x86_64-python-pip\n```\n\n3. **Set environment variables:**\n```bash\nexport PATH=\"/mingw64/bin:$PATH\"\nexport PYTHONHOME=/mingw64 \nexport PYTHONPATH=/mingw64/lib/python3.12\n```\n\n4. **Build the project:**\n```bash\n# Clean build\nmake rebuild\n\n# Check Python integration\nmake check-python\n```\n\n5. **Run the simulation:**\n```bash\nmake run\n```\n\n### **Troubleshooting**\n\n**Python Integration Issues:**\n- Ensure environment variables are set correctly\n- Verify Python headers: `test -f /mingw64/include/python3.12/Python.h`\n- Check library paths: `ls /mingw64/lib/libpython3.12*`\n\n**Build Errors:**\n- Use `make build-no-check` to skip Python verification\n- Check dependencies with `make install-deps`\n- Verify SDL2 installation: `pkg-config --cflags --libs sdl2`\n\n**Runtime Problems:**\n- Check file permissions on configuration files\n- Ensure `fish_controller.py` is in the project root\n- Monitor console output for specific error messages\n\n## Configuration System\n\n### **Plant Species Configuration** (`plants.conf`)\n\nConfigure 20 marine plant species with detailed properties:\n\n```ini\n[StaghornCoral]\ngrowth_probability=0.003          # Probability of growth each frame\ngrowth_attempts=5                 # Growth attempts per frame\nmax_branches=8                    # Maximum branching complexity\nbranch_distance=55.0              # Distance between growth nodes\nmobility_factor=0.05              # Movement flexibility\nage_mature=2400                   # Frames to reach maturity\nnutrition_depletion_strength=0.08 # Resource consumption impact\noxygen_production_factor=0.3      # Oxygen generation rate\noxygen_production_radius=90.0     # Oxygen effect radius\nnode_size_factor=1.0              # Visual size scaling\nchain_thickness_factor=1.0        # Connection thickness\nchain_curvature_factor=1.2        # Growth curvature\nnode_color=FF6B35                 # Plant node color (hex)\nchain_color=E55100                # Connection color (hex)\n```\n\n**Available Plant Species:**\n- **Hard Corals (9 species)**: StaghornCoral, TableCoral, BrainCoral, ElkhornCoral, PlantCoral, CoralletCoral, BushyCoral, CoralTree\n- **Soft Corals and Gorgonians (5 species)**: SoftCoral, SeaFan, SeaPlume, SeaWhip, GoldenSeaRod\n- **Marine Plants (3 species)**: Kelp, GiantKelp, SeaGrass\n- **Specialized Organisms (3 species)**: Sponge, AnemoneGarden, BlackCoral\n\n### **Fish Species Configuration** (`fish.conf`)\n\nConfigure 13 fish species with behavioral and neural network parameters:\n\n```ini\n[ParrotFish]\nmax_speed=8.0                     # Maximum swimming speed\nmax_force=2.0                     # Turning/acceleration force\nmass=1.2                          # Physical mass for physics\nsize_radius=7.0                   # Collision detection radius\neating_range=60.0                 # Distance to consume food\nfov_angle=220.0                   # Field of view (degrees)\nmax_turn_angle=55.0               # Maximum turning per frame\noxygen_reward_factor=0.015        # Reward scaling for oxygen\nproximity_reward_factor=0.01      # Reward for approaching food\neat_punishment=-0.02              # Penalty for failed eating attempts\nflow_sensitivity=0.25             # Response to water currents\ndanger_level=0.1                  # Threat level to other fish\nis_predator=0                     # 0=herbivore, 1=predator\neating_cooldown_frames=0          # Frames between eating attempts\nfish_detection_range=280.0        # Range to detect other fish\nmax_age=36000                     # Maximum lifespan (frames)\nnode_size_factor=0.8              # Visual size scaling\ntail_length_factor=1.0            # Tail length scaling\ntail_width_factor=1.0             # Tail width scaling\nnode_color=1E90FF                 # Fish color (hex)\n```\n\n**Available Fish Species:**\n- **Herbivorous Reef Fish (6 species)**: ClownFish, AngelFish, Parrotfish, SurgeonTang, Butterflyfish, Wrasse\n- **Predatory Fish (7 species)**: CoralTrout, Barracuda, ReefShark, TigerShark, GiantMorayEel, Grouper\n\n## Controls and User Interface\n\n### **Camera and Navigation**\n- **WASD**: Move camera around the ecosystem\n- **Shift+WASD**: Sprint camera movement for faster navigation\n- **Mouse Wheel**: Zoom in/out (unlimited zoom range)\n- **Mouse Drag**: Alternative camera movement\n\n### **Organism Placement**\n- **Left Click**: Place selected organism at cursor position\n- **Right Click**: Create plant chains (plant mode only)\n- **Tab**: Open comprehensive statistics monitor with temperature control\n- **Shift+Tab**: Toggle between plant and fish placement modes\n\n### **Species Selection**\n- **1-8**: Select plant species\n- **F1-F6**: Select fish species\n\n### **Visualization Layers**\n- **N**: Toggle nutrition layer visualization (shows food gradients)\n- **G**: Toggle oxygen layer visualization (shows gas distribution)\n- **F**: Toggle flow field visualization (shows water currents)\n- **R**: Toggle fish vision ray rendering (shows AI perception)\n\n### **System Controls**\n- **P**: Print detailed debug information to console\n- **ESC**: Exit simulation gracefully\n\n### **Statistics Monitor**\n\nPress **Tab** to open the real-time ecosystem statistics window featuring:\n\n- **Population Tracking**: Live counts of fish and plant populations\n- **Temperature Control**: Slider to adjust ecosystem temperature (0.0°C to 3.0°C)\n- **Coral Bleaching**: Visual monitoring of temperature effects on coral health\n- **Neural Network Performance**: Tracking of AI learning progress and reproduction success\n- **Environmental Metrics**: nutrition balance and ecosystem health\n\n## Neural Network Learning System\n\n### **Training Process**\n\nFish agents learn through continuous interaction with the environment:\n\n1. **Sensory Input**: Each fish processes 7 environmental inputs every frame\n2. **Decision Making**: Neural network outputs 3 action values\n3. **Action Execution**: Fish performs movement and feeding behaviors\n4. **Reward Calculation**: Multi-component reward based on survival factors\n5. **Learning Update**: Weights adjusted using gradient descent with experience replay\n\n### **Reward Structure**\n\n**Positive Rewards:**\n* **Proximity to food sources**: Strong rewards for finding plants (herbivores) or prey fish (predators)\n* **Successful consumption**: Large rewards for actual eating of plants, fish, or corpses\n* **Predator avoidance**: Rewards for escaping from threats (herbivores fleeing from predators)\n* **Reproduction success**: Large rewards (+150-200) for successful reproduction events\n* **Basic survival**: Small continuous reward (+0.001) just for staying alive\n* **Oxygen level rewards**: Rewards based on current oxygen level (species-specific oxygen_reward_factor)\n\n**Negative Rewards:**\n* **Failed eating attempts**: Punishment values from configuration (eat_punishment: -0.015 to -0.05)\n* **Excessive spinning**: Penalties for high turn amounts (\u003e0.6) and sustained spinning behavior\n* **Approaching threats**: Penalties for moving toward predators (herbivores) or stronger predators\n* **Stillness when prey visible**: Predators get penalized for not pursuing visible prey\n\n### **Evolution and Inheritance**\n\nWhen fish reproduce:\n- Parent neural networks are copied to offspring with small random mutations\n- Successful parents (high reproduction count + reward) are more likely to pass on traits\n- Generation tracking allows monitoring of evolutionary progress\n- Best-performing models are automatically saved for analysis\n\n### **Model Persistence**\n\nThe system tracks neural network performance and evolution:\n- **Performance Tracking**: Monitors reproduction success, survival time, and reward accumulation\n- **Generation Tracking**: Allows monitoring of evolutionary progress across fish generations\n- **Best Performer Identification**: Automatically identifies and tracks the most successful neural networks\n\n## Scientific Accuracy and Biological Modeling\n\n### **Marine Biology Concepts**\n\n**Direct Target Detection:**\n- Fish use line-of-sight algorithms to locate food sources within their field of view\n- Detection range and field of view angle vary by species (110°-260° FOV)\n- Fish efficiently identify the nearest available food source or threat\n\n**Photosynthesis and Oxygen Production:**\n- Plants generate oxygen at species-specific rates (oxygen_production_factor: 0.05-0.85)\n- Oxygen diffuses through water creating environmental gradients\n- Fish consume oxygen based on activity level and species metabolism\n\n**Nutrient Cycling:**\n- Plant consumption depletes local nutrition sources\n- Fish digestion produces waste that fertilizes nearby plants\n- Corpses from dead fish provide additional nutrition sources\n- Ecosystem maintains dynamic equilibrium through these cycles\n\n**Territorial and Social Behavior:**\n- Spatial competition for resources drives territorial behavior\n- Predator-prey relationships create realistic hunting dynamics\n- Field of view limitations create natural territorial boundaries\n- Individual fish behaviors aggregate into emergent group patterns\n\n### **Environmental Factors**\n\n**Temperature Effects:**\n- Coral bleaching occurs when temperature exceeds optimal ranges\n- Bleached corals appear white/gray and stop producing oxygen\n- Temperature affects entire coral colonies including growth connections\n- Higher temperatures increase bleaching probability exponentially\n\n**Flow Dynamics:**\n- Water currents influence fish movement and energy expenditure\n- Flow fields create realistic underwater movement patterns\n- Fish learn to use currents for efficient transportation\n\n## Development and Extensibility\n\n### **Adding New Species**\n\n**New Plant Species:**\n1. Add configuration section to `plants.conf`\n2. Specify growth parameters, visual properties, and environmental effects\n3. Plants are automatically loaded and available for placement\n\n**New Fish Species:**\n1. Add configuration section to `fish.conf`\n2. Define behavioral parameters, neural network settings, and visual properties\n3. Fish inherit the same neural network architecture with species-specific tuning\n\n### **Extending Neural Networks**\n\n**Modifying Network Architecture:**\n1. Adjust `RL_INPUT_SIZE` and `RL_OUTPUT_SIZE` in `types.h`\n2. Update input generation in `fish_update_rl_inputs()`\n3. Modify output handling in `fish_apply_rl_outputs()`\n4. Update Python neural network class in `fish_controller.py`\n\n**Adding New Sensors:**\n1. Implement sensor logic in fish behavior system\n2. Add input processing to neural network\n3. Update reward calculation for new sensory information\n\n### **Building Custom Scenarios**\n\n**Environmental Presets:**\n- Modify `populate_reef_randomly()` in `main.c` for custom initial conditions\n- Adjust temperature, plant distribution, and fish populations\n- Create specialized ecosystems for research or demonstration\n\n**Experimental Parameters:**\n- Tune learning rates and exploration parameters in `fish_controller.py`\n- Modify reward structures for different behavioral goals\n- Implement new fitness metrics for evolutionary analysis\n\n## Research Applications\n\n### **Educational Use Cases**\n\n**Marine Biology Education:**\n- Visualize complex ecosystem interactions\n- Demonstrate predator-prey dynamics\n- Explore effects of environmental changes\n\n**Artificial Intelligence Learning:**\n- Study emergent behaviors in multi-agent systems\n- Analyze neural network learning in dynamic environments\n- Compare different reinforcement learning approaches\n\n**Environmental Science:**\n- Model climate change effects on coral reefs\n- Simulate coral bleaching scenarios\n- Study ecosystem resilience and recovery\n\n### **Research Extensions**\n\n**Possible Research Directions:**\n- Genetic algorithms for neural network evolution\n- Multi-species cooperation and competition dynamics\n- Environmental disturbance response patterns\n- Collective intelligence and swarm behaviors\n- Climate change impact modeling\n\n**Data Collection:**\n- Neural network performance metrics\n- Population dynamics over time\n- Behavioral pattern analysis\n- Environmental response studies\n\n## Troubleshooting and FAQ\n\n### **Common Issues**\n\n**Q: Simulation fails to start with Python errors**\nA: Ensure the required environment variables are set correctly.\n\n**Q: Fish are not moving or learning**\nA: Check that `fish_controller.py` loaded successfully. Look for \"Neural network script loaded successfully!\" in console output.\n\n**Q: Build fails with SDL2 errors**\nA: Install SDL2 development libraries: `pacman -S mingw-w64-x86_64-SDL2`\n\n**Q: Performance is slow with many entities**\nA: Reduce initial population counts or disable expensive visual layers (nutrition, oxygen rendering).\n\n**Q: Neural networks are not learning effectively**\nA: Adjust learning parameters in `fish_controller.py`. Increase `learning_rate` or modify `exploration_rate` decay.\n\n**Q: Statistics window doesn't open**\nA: Ensure Python tkinter is available: `python -c \"import tkinter\"`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fortanav2%2Fthinkblue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fortanav2%2Fthinkblue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fortanav2%2Fthinkblue/lists"}