Skip to content

README.md

Latest commit

 

History

History
87 lines (67 loc) · 3.12 KB

README.md

File metadata and controls

87 lines (67 loc) · 3.12 KB
Raw

SHEEP HERDING SIMULATION 🐑🎮

A realistic, modular, AI-driven sheep herding simulation built in Python with Pygame. Watch advanced flocking behaviors, strategic shepherding AI, and online learning come together in one interactive demo!

VIDEO DEMO :

Code_mgVMgzJSuO.mp4

✨ KEY FEATURES ✨

  • Modular architecture -- tweak everything in one config file (config.py)\
  • Advanced flocking rules -- separation, alignment, cohesion plus a fear-response system for emergent collective movement\
  • Smart Shepherd Dog 🤖
    -- Limited perception via configurable vision radius
    -- k-Nearest Neighbors to focus on the most influential sheep
    -- Multi-criteria scoring: distance, alignment, local density, boundary proximity
    -- Online learning (gradient descent) to adapt feature weights in real time
    -- Strategic positioning behind the furthest sheep relative to your target\
  • Interactive debug overlays -- toggle vision radius, connection lines, AI decision scores\
  • Live console output -- see feature weights update as the dog's strategy evolves

🚀 INSTALLATION & SETUP 🚀

  1. Clone the repo:
    git clone https://github.com/cipherpodliq1/sheep-herding-simulation.git
    cd sheep-herding-simulation

  2. (Optional) Create + activate virtual environment:\

    • macOS/Linux:
      python3 -m venv venv
      source venv/bin/activate\
    • Windows:
      python3 -m venv venv
      venv\Scripts\activate

  3. Install dependencies:
    pip install -r requirements.txt

⚙️ CONFIGURATION ⚙️\

All parameters live in config.py for easy tweaking!
VISION_RADIUS -- Dog's view range (default 150)
K_NEIGHBORS -- Number of sheep to consider (default 5)
SHEEP_COUNT -- Total flock size (default 50)
COHESION_WEIGHT -- Cohesion rule weight (default 1.0)
DOG_LEARNING_RATE -- Online learning rate (default 0.01)

▶️ USAGE ▶️\

Run the sim:
python main.py
Watch as the AI dog learns, adapts, and refines its herding strategy over time!

🎮 CONTROLS 🎮\

  • SPACE -- Pause / Resume\
  • D -- Toggle debug info (AI scoring per sheep)\
  • V -- Toggle vision radius overlay\
  • C -- Toggle connection lines to neighbors\
  • Left Click -- Move the target point\
  • R -- Reset simulation

📁 FILE STRUCTURE 📁\

config.py -- Centralized parameters & constants
vector_utils.py -- 2D vector math helpers
sheep.py -- Flocking & fear-response logic
dog.py -- AI decision pipelines & online learning
environment.py -- Simulation manager (state & rendering)
main.py -- Entry point (Pygame loop)
requirements.txt -- Dependencies (pygame, numpy, sklearn)

📝 DOCUMENTATION 📝\

Inline docstrings and comments explain every module!\

  • dog.py -- Dive into decision-making, scoring, and learning\
  • sheep.py -- See how flocking and fear responses produce lifelike movement

🙌 WANT TO CONTRIBUTE? 🙌
We welcome your ideas, enhancements, and optimizations!

  1. Fork the repo

  2. Create a feature branch

  3. Submit a pull request

Let's build the ultimate sheep herding AI together!

🔗 CONNECT WITH ME 🔗
LinkedIn: https://www.linkedin.com/in/kristiyan-radev/

Happy herding! 🐕✨