How vitthalhumbe/fishpond works
1. What this repository is
- A single-process Python simulation of an ecosystem.
- It combines a real-time Pygame visual simulation with a genetic algorithm that evolves fish traits over generations.
2. Execution boundary
- The project is run from algorithm/main.py.
- That file is the top-level orchestrator: it starts the simulation loop, updates agents each frame, and triggers any result graphing/visualization.
3. Core runtime loop
- The simulation is stateful and frame-driven.
- Each tick updates fish movement, shark pursuit, collisions/encounters, survival status, and generation progression.
- The loop is also responsible for rendering the current world state in Pygame.
4. Agent model: algorithm/agents.py
- This is the behavioral layer for the two entity types: fish and shark.
- Fish implement flocking-style motion: alignment, separation, and cohesion, plus individual traits that affect survival.
- The shark acts as a predator with a vision cone / detection logic and chase behavior when fish enter range.
5. Evolution engine: algorithm/genetic_algorithm.py
- This module handles the generational boundary between simulations.
- It selects surviving fish, applies crossover and mutation, and produces the next population.
- The evolved output is a new set of fish traits, not a new architecture level; the simulation remains the same, but the population parameters change.
6. Configuration boundary: algorithm/variables.py
- Central place for tunable constants such as screen size, population count, speeds, vision ranges, and likely mutation/evolution settings.
- This module acts as the shared config source for both the simulation and the genetic algorithm.
7. Visualization and metrics
- algorithm/graphs.py appears to provide result plotting or analysis of simulation outcomes across generations.
- The README also mentions “graphing,” so the architecture likely includes a post-run or side-panel visualization path for performance over time.
8. Data flow between modules
- variables.py defines the constants used by both agent behavior and evolutionary rules.
- agents.py produces the per-frame state updates and survival outcomes.
- genetic_algorithm.py consumes those outcomes at the end of a generation and returns a new population.
- main.py coordinates this loop and passes data to rendering/graphs.
9. Important domain boundaries
- Simulation boundary: the real-time world of fish and shark in Pygame.
- Evolution boundary: generation transitions where traits are copied, crossed, and mutated.
- Analysis boundary: graphing/reporting of results, separate from the live agent behavior.
10. External dependencies that matter
- Pygame is the rendering/input/timing layer and defines the interactive simulation runtime.
- NumPy is likely used for vector math and population/fitness calculations.
- There is no indication of a backend server, database, or network dependency.
11. Project structure implications
- This is not a multi-service app; it is a compact simulation program with a clear split between orchestration, agent behavior, evolutionary logic, and configuration.
- For an architecture diagram, the main boxes should be: main.py at center, agents.py and genetic_algorithm.py as the two logic subsystems, variables.py as shared config, and graphs.py as the reporting/analysis path.
12. How to think about the system
- The fish population is the evolving asset.
- The shark is the environmental pressure.
- Survival time is the implicit fitness signal that feeds the genetic algorithm.
- The simulation repeats until a generation ends, then the next population is synthesized and the cycle continues.
Main entry points: main.py Main loop · variables.py Variables · genetic_algorithm.py Select · agents.py Fish
Components 10
Runtime
Live simulation and agent behavior.
- Main loop · Top-level entrypoint that runs the frame loop, coordinates updates, and triggers generation changes and visualization.
algorithm/main.py - Fish · Evolving prey agents with flocking behavior and trait-driven survival.
algorithm/agents.py - Shark · Predator agent with detection and chase behavior that pressures fish survival.
algorithm/agents.py
Evolution
Generation boundary and trait regeneration.
- Select · Chooses surviving fish that seed the next generation.
algorithm/genetic_algorithm.py - Crossover · Combines parent traits to produce offspring candidates.
algorithm/genetic_algorithm.py - Mutate · Applies random trait changes to preserve diversity across generations.
algorithm/genetic_algorithm.py
Analysis
Outcome plotting and reporting.
- Graphs · Plots or summarizes simulation outcomes across generations.
algorithm/graphs.py
Shared
Central configuration used across subsystems.
- Variables · Shared simulation constants for world size, populations, speeds, ranges, and mutation settings.
algorithm/variables.py
External
Runtime dependencies outside the repository.
- Pygame · External rendering, timing, and interaction runtime for the live simulation.
- NumPy · External numerical library for vector and population calculations.
Connections 14
- Main loop → Fish: updates · Runs per-frame fish behavior and state updates.
- Main loop → Shark: updates · Advances predator movement and pursuit each tick.
- Main loop → Select: ends gen · Hands off survival outcomes when a generation completes.
- Select → Crossover: parents · Uses survivors as inputs for offspring creation.
- Crossover → Mutate: offspring · Mutated children become the next candidate population.
- Mutate → Fish: next pop · Produces the next generation of fish traits.
- Main loop → Graphs: reports · Sends generation results for plotting or analysis.
- Variables → Main loop: tunes · Provides shared runtime constants.
- Variables → Fish: tunes · Feeds flocking, movement, and vision parameters.
- Variables → Shark: tunes · Feeds predator speed and detection parameters.
- Variables → Select: tunes · Defines population and evolution settings.
- Main loop → Pygame: renders · Uses Pygame for the visual simulation loop.
- Fish → NumPy: vectors · Relies on numerical/vector operations for movement and fitness math.
- Select → NumPy: fitness · Uses numerical routines for population scoring and selection.