boids_simulation.py

import sys
import os
import math
import json
import time
import threading
import pygame
import numpy as np
import asyncio
from typing import List, Tuple, Dict, Optional, Set, Union
from pygame.math import Vector2

# ==== Custom Exceptions ====
class FeatureTestError(Exception):
    """Raised when a feature test fails."""
    pass

class PerformanceError(Exception):
    """Raised when performance drops below minimum requirements."""
    pass

class OptimizationRequiredError(Exception):
    """Raised when system needs performance improvements."""
    pass

# ==== Configuration System ====
class ConfigManager:
    """Manages loading and accessing configuration parameters."""
    defaultConfigFile = "config.json"

    def __init__(self, configFile: Optional[str] = None):
        self.configFile = configFile or self.defaultConfigFile
        self.configData = {}
        self._loadConfig()

    def _loadConfig(self) -> None:
        try:
            with open(self.configFile, 'r') as f:
                self.configData = json.load(f)
        except (IOError, json.JSONDecodeError):
            self.configData = self._defaultConfig()
        self._validateConfig()

    def _validateConfig(self):
        # Placeholder for validations and setting defaults if missing
        defaults = self._defaultConfig()
        for key, val in defaults.items():
            if key not in self.configData:
                self.configData[key] = val

    @staticmethod
    def _defaultConfig() -> dict:
        return {
            "screenWidth": 1200,
            "screenHeight": 800,
            "boidCount": 160,
            "predatorCount": 10,
            "obstacleCount": 20,
            "leaderCount": 10,
            "maxSpeed": 4.0,
            "maxForce": 0.1,
            "neighborRadius": 50,
            "desiredSeparation": 20,
            "predatorAvoidRadius": 80,
            "obstacleAvoidRadius": 40,
            "gridCellSize": 80,
            "fpsTarget": 60,
            "speedMultiplier": 1.0,
            "visualizeGrid": False,
            "visualizationMode": 0,  # 0=normal,1=grid,2=debug
            "backgroundColor": [25, 25, 25],
            "boidColor": [200, 200, 255],
            "predatorColor": [255, 50, 50],
            "obstacleColor": [100, 100, 100],
            "leaderColor": [255, 255, 100],
            "maxAgentCount": 250,
            "accelerationFactor": 1.0,
            "environmentalWind": [0.0, 0.0],
            "adaptiveBehaviorEnabled": True,
            "learningRate": 0.05,
            "splitMergeEnabled": True,
            "scoreOutputFile": "boids_simulation_score.json"
        }

    def get(self, key: str, default=None):
        return self.configData.get(key, default)

# ==== Vector Utilities ====
def limitVector(vec: Vector2, maxVal: float) -> Vector2:
    if vec.length_squared() > maxVal * maxVal:
        vec = vec.normalize() * maxVal
    return vec

# ==== Agent Base Class ====
class Agent:
    """
    Base class for all agents with position, velocity, acceleration and common methods.
    """
    __slots__ = ('position', 'velocity', 'acceleration', 'maxSpeed', 'maxForce', 'radius', 'id')

    idCounter = 0

    def __init__(self, position: Vector2, velocity: Vector2, maxSpeed: float, maxForce: float, radius: float):
        self.position: Vector2 = position
        self.velocity: Vector2 = velocity
        self.acceleration: Vector2 = Vector2(0, 0)
        self.maxSpeed: float = maxSpeed
        self.maxForce: float = maxForce
        self.radius: float = radius
        self.id: int = Agent.idCounter
        Agent.idCounter += 1

    def applyForce(self, force: Vector2) -> None:
        self.acceleration += force

    def update(self) -> None:
        self.velocity += self.acceleration
        self.velocity = limitVector(self.velocity, self.maxSpeed)
        self.position += self.velocity
        self.acceleration *= 0

    def edges(self, width: int, height: int) -> None:
        # Wrap boundary handling
        if self.position.x < 0:
            self.position.x += width
        elif self.position.x >= width:
            self.position.x -= width
        if self.position.y < 0:
            self.position.y += height
        elif self.position.y >= height:
            self.position.y -= height

    def distanceTo(self, other: 'Agent') -> float:
        return self.position.distance_to(other.position)

    def __repr__(self):
        return f"<Agent id={self.id} pos={self.position} vel={self.velocity}>"

# ==== Agent Types ====
class Boid(Agent):
    def __init__(self, position: Vector2, velocity: Vector2, config: ConfigManager):
        super().__init__(position, velocity, config.get("maxSpeed", 4.0), config.get("maxForce", 0.1), 5.0)
        self.config = config
        self.state = "normal"  # could be "normal", "fleeing", "followingLeader"
        self.leaderTarget: Optional[Agent] = None

    def flock(self, neighbors: List['Boid'], predators: List['Predator'], obstacles: List['Obstacle']) -> None:
        sep = self.separate(neighbors)
        ali = self.align(neighbors)
        coh = self.cohesion(neighbors)
        obs = self.avoidObstacles(obstacles)
        pre = self.evadePredators(predators)
        led = self.followLeader()

        # Weighting behaviors
        sep *= 1.5
        ali *= 1.0
        coh *= 1.0
        obs *= 2.0
        pre *= 3.0
        led *= 1.5

        self.applyForce(sep)
        self.applyForce(ali)
        self.applyForce(coh)
        self.applyForce(obs)
        self.applyForce(pre)
        self.applyForce(led)

    def separate(self, neighbors: List['Boid']) -> Vector2:
        desiredSeparation = self.config.get("desiredSeparation", 20)
        steer = Vector2(0, 0)
        count = 0
        for other in neighbors:
            d = self.position.distance_to(other.position)
            if 0 < d < desiredSeparation:
                diff = self.position - other.position
                if d > 0:
                    diff /= d
                steer += diff
                count += 1
        if count > 0:
            steer /= count
        if steer.length_squared() > 0:
            steer = steer.normalize() * self.maxSpeed - self.velocity
            steer = limitVector(steer, self.maxForce)
        return steer

    def align(self, neighbors: List['Boid']) -> Vector2:
        neighborDist = self.config.get("neighborRadius", 50)
        sumV = Vector2(0, 0)
        count = 0
        for other in neighbors:
            d = self.position.distance_to(other.position)
            if 0 < d < neighborDist:
                sumV += other.velocity
                count += 1
        if count > 0:
            sumV /= count
            sumV = sumV.normalize() * self.maxSpeed
            steer = sumV - self.velocity
            steer = limitVector(steer, self.maxForce)
            return steer
        else:
            return Vector2(0, 0)

    def cohesion(self, neighbors: List['Boid']) -> Vector2:
        neighborDist = self.config.get("neighborRadius", 50)
        sumPos = Vector2(0, 0)
        count = 0
        for other in neighbors:
            d = self.position.distance_to(other.position)
            if 0 < d < neighborDist:
                sumPos += other.position
                count += 1
        if count > 0:
            avgPos = sumPos / count
            return self.seek(avgPos)
        else:
            return Vector2(0, 0)

    def seek(self, target: Vector2) -> Vector2:
        desired = target - self.position
        d = desired.length()
        if d > 0:
            desired = desired.normalize() * self.maxSpeed
            steer = desired - self.velocity
            steer = limitVector(steer, self.maxForce)
            return steer
        return Vector2(0, 0)

    def avoidObstacles(self, obstacles: List['Obstacle']) -> Vector2:
        steer = Vector2(0, 0)
        count = 0
        avoidRadius = self.config.get("obstacleAvoidRadius", 40)
        for obs in obstacles:
            d = self.position.distance_to(obs.position)
            if d < avoidRadius + obs.radius:
                diff = self.position - obs.position
                if d > 0:
                    diff /= d
                steer += diff
                count += 1
        if count > 0:
            steer /= count
            if steer.length_squared() > 0:
                steer = steer.normalize() * self.maxSpeed - self.velocity
                steer = limitVector(steer, self.maxForce * 2)
        return steer

    def evadePredators(self, predators: List['Predator']) -> Vector2:
        steer = Vector2(0, 0)
        count = 0
        avoidRadius = self.config.get("predatorAvoidRadius", 80)
        for pred in predators:
            d = self.position.distance_to(pred.position)
            if d < avoidRadius:
                diff = self.position - pred.position
                if d > 0:
                    diff /= d
                steer += diff
                count += 1
        if count > 0:
            steer /= count
            if steer.length_squared() > 0:
                steer = steer.normalize() * self.maxSpeed * 2 - self.velocity
                steer = limitVector(steer, self.maxForce * 3)
        return steer

    def followLeader(self) -> Vector2:
        if self.leaderTarget is None:
            return Vector2(0, 0)
        dist = self.position.distance_to(self.leaderTarget.position)
        if dist > 100:
            return self.seek(self.leaderTarget.position)
        return Vector2(0, 0)

    def update(self) -> None:
        super().update()
        # possible adaptive behavior here
        if self.config.get("adaptiveBehaviorEnabled", True):
            speed = self.velocity.length()
            if speed < self.maxSpeed * 0.5:
                self.maxForce *= 1.05
            else:
                self.maxForce *= 0.95
            self.maxForce = max(0.05, min(self.maxForce, 0.2))

class Predator(Agent):
    def __init__(self, position: Vector2, velocity: Vector2, config: ConfigManager):
        super().__init__(position, velocity, config.get("maxSpeed", 4.5)*1.2, config.get("maxForce", 0.1)*1.5, 7.0)
        self.config = config
        self.targetPrey: Optional[Boid] = None

    def hunt(self, preyList: List[Boid]) -> None:
        closestPrey = None
        closestDist = float('inf')
        for prey in preyList:
            d = self.position.distance_to(prey.position)
            if d < closestDist:
                closestDist = d
                closestPrey = prey
        if closestPrey:
            seekForce = self.seek(closestPrey.position)
            self.applyForce(seekForce)

    def seek(self, target: Vector2) -> Vector2:
        desired = target - self.position
        d = desired.length()
        if d > 0:
            desired = desired.normalize() * self.maxSpeed
            steer = desired - self.velocity
            steer = limitVector(steer, self.maxForce)
            return steer
        return Vector2(0, 0)

    def update(self) -> None:
        super().update()

class Obstacle(Agent):
    def __init__(self, position: Vector2, radius: float):
        super().__init__(position, Vector2(0, 0), 0, 0, radius)

    def update(self) -> None:
        pass  # obstacles don't move

class Leader(Boid):
    def __init__(self, position: Vector2, velocity: Vector2, config: ConfigManager):
        super().__init__(position, velocity, config)
        self.radius = 6.0

    def flock(self, neighbors: List['Boid'], predators: List['Predator'], obstacles: List['Obstacle']) -> None:
        # Leaders behave like boids but with stronger cohesion (leading)
        sep = self.separate(neighbors)
        ali = self.align(neighbors)
        coh = self.cohesion(neighbors) * 1.5
        obs = self.avoidObstacles(obstacles)
        pre = self.evadePredators(predators)

        sep *= 1.5
        ali *= 1.0
        obs *= 2.0
        pre *= 3.0

        self.applyForce(sep)
        self.applyForce(ali)
        self.applyForce(coh)
        self.applyForce(obs)
        self.applyForce(pre)

# ==== Spatial Hash Grid ====
class SpatialHashGrid:
    """
    Efficient spatial hash grid for neighbor searching and collision detection.
    """
    def __init__(self, width: int, height: int, cellSize: int):
        self.width = width
        self.height = height
        self.cellSize = cellSize
        self.cols = (width // cellSize) + 1
        self.rows = (height // cellSize) + 1
        self.grid: Dict[Tuple[int, int], List[Agent]] = {}

    def _hash(self, position: Vector2) -> Tuple[int, int]:
        col = int(position.x // self.cellSize)
        row = int(position.y // self.cellSize)
        return (col, row)

    def clear(self) -> None:
        self.grid.clear()

    def insert(self, agent: Agent) -> None:
        cell = self._hash(agent.position)
        if cell not in self.grid:
            self.grid[cell] = []
        self.grid[cell].append(agent)

    def query(self, position: Vector2, radius: float) -> List[Agent]:
        col, row = self._hash(position)
        nearbyAgents: List[Agent] = []
        cellsRange = int(math.ceil(radius / self.cellSize)) + 1

        for dx in range(-cellsRange, cellsRange + 1):
            for dy in range(-cellsRange, cellsRange + 1):
                cell = (col + dx, row + dy)
                if cell in self.grid:
                    for agent in self.grid[cell]:
                        if agent.position.distance_to(position) <= radius:
                            nearbyAgents.append(agent)
        return nearbyAgents

    def getAllAgents(self) -> List[Agent]:
        allAgents = []
        for agents in self.grid.values():
            allAgents.extend(agents)
        return allAgents

    def cells(self) -> List[Tuple[int, int]]:
        return list(self.grid.keys())

# ==== Score Manager ====
class ScoreManager:
    """
    Evaluates the simulation on a 100-point scale based on feature correctness, performance, and code quality.
    """
    def __init__(self, config: ConfigManager):
        self.config = config
        self.scores = {
            "flocking": 0,
            "spatialHash": 0,
            "obstacleAvoidance": 0,
            "predatorPrey": 0,
            "uiControls": 0,
            "performance": 0,
            "codeQuality": 0,
            "documentation": 0,
            "errorHandling": 0,
            "testing": 0
        }
        self.featureWeights = {
            "flocking": 20,
            "spatialHash": 15,
            "obstacleAvoidance": 10,
            "predatorPrey": 10,
            "uiControls": 10,
            "performance": 15,
            "codeQuality": 10,
            "documentation": 5,
            "errorHandling": 5,
            "testing": 5
        }

    def computePerformanceScore(self, fps: float, agentCount: int) -> None:
        targetFPS = self.config.get("fpsTarget", 60)
        if fps >= targetFPS and agentCount >= 200:
            self.scores["performance"] = 18 + 2
        elif fps >= 45 and agentCount >= 200:
            self.scores["performance"] = 10 + (fps - 45) / 15 * 5
        elif fps >= 30 and agentCount >= 200:
            self.scores["performance"] = 5 + (fps - 30) / 15 * 4
        else:
            self.scores["performance"] = 0

    def calculateTotalScore(self) -> int:
        total = 0
        for feature, weight in self.featureWeights.items():
            score = self.scores.get(feature, 0)
            total += min(score, weight)
        return int(total)

    def report(self) -> None:
        total = self.calculateTotalScore()
        print(f"BOIDS_SIMULATION_SCORE: {total}/100\n")
        print("Score Breakdown:")
        for feature, weight in self.featureWeights.items():
            score = min(self.scores.get(feature, 0), weight)
            print(f"- {feature.replace('_', ' ').title()}: {score}/{weight}")
        print("\nRecommendations:")
        # Simplified recommendations placeholder
        if self.scores["performance"] < 15:
            print("- Optimize spatial hash grid cell size and collision detection.")
        if self.scores["flocking"] < 15:
            print("- Improve flocking cohesion and separation behaviors.")
        if self.scores["obstacleAvoidance"] < 8:
            print("- Enhance obstacle avoidance steering calculations.")
        if self.scores["predatorPrey"] < 8:
            print("- Refine predator-prey interaction logic.")
        if self.scores["uiControls"] < 8:
            print("- Add more interactive controls and visualization modes.")
        if self.scores["codeQuality"] < 8:
            print("- Improve code modularity, naming, and documentation.")
        if self.scores["testing"] < 4:
            print("- Expand automated testing coverage and reporting.")

    def saveJsonReport(self, filename: str) -> None:
        data = {
            "totalScore": self.calculateTotalScore(),
            "featureScores": self.scores,
            "weights": self.featureWeights
        }
        try:
            with open(filename, 'w') as f:
                json.dump(data, f, indent=2)
        except IOError:
            pass

# ==== Simulation Controller ====
class Simulation:
    """
    Core simulation class managing agents, spatial grid, behaviors, rendering, and input.
    """
    def __init__(self, config: ConfigManager):
        pygame.init()
        self.config = config
        self.screenWidth = config.get("screenWidth", 1200)
        self.screenHeight = config.get("screenHeight", 800)
        self.screen = pygame.display.set_mode((self.screenWidth, self.screenHeight))
        pygame.display.set_caption("Boids++ Simulation")
        self.clock = pygame.time.Clock()
        self.font = pygame.font.SysFont("consolas", 16)
        self.running = True
        self.speedMultiplier = config.get("speedMultiplier", 1.0)
        self.visualizeGrid = config.get("visualizeGrid", False)
        self.visualizationMode = config.get("visualizationMode", 0)
        self.backgroundColor = config.get("backgroundColor", [25, 25, 25])
        self.gridCellSize = config.get("gridCellSize", 80)
        self.grid = SpatialHashGrid(self.screenWidth, self.screenHeight, self.gridCellSize)

        self.boids: List[Boid] = []
        self.predators: List[Predator] = []
        self.obstacles: List[Obstacle] = []
        self.leaders: List[Leader] = []

        self._initAgents()

        self.frameCount = 0
        self.fpsHistory = []
        self.lastFpsCheck = time.time()
        self.fps = 0.0

        self.scoreManager = ScoreManager(config)

        # Controls
        self.showHelp = True
        self.paused = False

    def _initAgents(self) -> None:
        # Initialize Boids
        for _ in range(self.config.get("boidCount", 160)):
            pos = Vector2(np.random.uniform(0, self.screenWidth),
                          np.random.uniform(0, self.screenHeight))
            vel = Vector2(np.random.uniform(-1, 1), np.random.uniform(-1, 1))
            vel.scale_to_length(np.random.uniform(1.0, self.config.get("maxSpeed", 4.0)))
            b = Boid(pos, vel, self.config)
            self.boids.append(b)

        # Initialize Predators
        for _ in range(self.config.get("predatorCount", 10)):
            pos = Vector2(np.random.uniform(0, self.screenWidth),
                          np.random.uniform(0, self.screenHeight))
            vel = Vector2(np.random.uniform(-1, 1), np.random.uniform(-1, 1))
            vel.scale_to_length(np.random.uniform(1.0, self.config.get("maxSpeed", 4.5)*1.2))
            p = Predator(pos, vel, self.config)
            self.predators.append(p)

        # Initialize Obstacles
        for _ in range(self.config.get("obstacleCount", 20)):
            pos = Vector2(np.random.uniform(0, self.screenWidth),
                          np.random.uniform(0, self.screenHeight))
            r = np.random.uniform(10, 20)
            o = Obstacle(pos, r)
            self.obstacles.append(o)

        # Initialize Leaders
        for _ in range(self.config.get("leaderCount", 10)):
            pos = Vector2(np.random.uniform(0, self.screenWidth),
                          np.random.uniform(0, self.screenHeight))
            vel = Vector2(np.random.uniform(-1, 1), np.random.uniform(-1, 1))
            vel.scale_to_length(np.random.uniform(1.0, self.config.get("maxSpeed", 4.0)))
            l = Leader(pos, vel, self.config)
            self.leaders.append(l)

        # Assign leaders to boids for following behavior
        for i, boid in enumerate(self.boids):
            boid.leaderTarget = self.leaders[i % len(self.leaders)] if self.leaders else None

    def _populateSpatialGrid(self) -> None:
        self.grid.clear()
        for agent in self.boids + self.predators + self.obstacles + self.leaders:
            self.grid.insert(agent)

    def _updateAgents(self) -> None:
        # Boids flocking behavior
        for boid in self.boids:
            neighbors = self.grid.query(boid.position, self.config.get("neighborRadius", 50))
            boidNeighbors = [a for a in neighbors if isinstance(a, Boid) and a is not boid]
            predatorsNearby = [a for a in neighbors if isinstance(a, Predator)]
            obstaclesNearby = [a for a in neighbors if isinstance(a, Obstacle)]
            boid.flock(boidNeighbors, predatorsNearby, obstaclesNearby)
        # Leaders flocking behavior
        for leader in self.leaders:
            neighbors = self.grid.query(leader.position, self.config.get("neighborRadius", 50))
            boidNeighbors = [a for a in neighbors if isinstance(a, Boid) and a is not leader]
            predatorsNearby = [a for a in neighbors if isinstance(a, Predator)]
            obstaclesNearby = [a for a in neighbors if isinstance(a, Obstacle)]
            leader.flock(boidNeighbors, predatorsNearby, obstaclesNearby)
        # Predators hunting
        for predator in self.predators:
            preyList = self.grid.query(predator.position, self.config.get("neighborRadius", 120))
            preyList = [p for p in preyList if isinstance(p, Boid)]
            predator.hunt(preyList)

        # Update all agents
        for agent in self.boids + self.leaders + self.predators + self.obstacles:
            agent.update()
            agent.edges(self.screenWidth, self.screenHeight)

    def _handleEvents(self) -> None:
        for event in pygame.event.get():
            if event.type == pygame.QUIT:
                self.running = False
            elif event.type == pygame.KEYDOWN:
                if event.key == pygame.K_ESCAPE:
                    self.running = False
                elif event.key == pygame.K_SPACE:
                    self.paused = not self.paused
                elif event.key == pygame.K_g:
                    self.visualizeGrid = not self.visualizeGrid
                elif event.key == pygame.K_v:
                    self.visualizationMode = (self.visualizationMode + 1) % 3
                elif event.key == pygame.K_PLUS or event.key == pygame.K_EQUALS:
                    self.speedMultiplier = min(self.speedMultiplier + 0.1, 10.0)
                elif event.key == pygame.K_MINUS or event.key == pygame.K_UNDERSCORE:
                    self.speedMultiplier = max(self.speedMultiplier - 0.1, 0.1)
                elif event.key == pygame.K_h:
                    self.showHelp = not self.showHelp

    def _drawAgents(self) -> None:
        # Draw obstacles first
        for obstacle in self.obstacles:
            pygame.draw.circle(self.screen, self.config.get("obstacleColor", [100, 100, 100]),
                               (int(obstacle.position.x), int(obstacle.position.y)), int(obstacle.radius))

        # Draw predators
        for predator in self.predators:
            self._drawAgentTriangle(predator, self.config.get("predatorColor", [255, 50, 50]))

        # Draw leaders
        for leader in self.leaders:
            self._drawAgentTriangle(leader, self.config.get("leaderColor", [255, 255, 100]))

        # Draw boids
        for boid in self.boids:
            self._drawAgentTriangle(boid, self.config.get("boidColor", [200, 200, 255]))

    def _drawAgentTriangle(self, agent: Agent, color: List[int]) -> None:
        # Draw a triangle pointing in direction of velocity
        pos = agent.position
        vel = agent.velocity
        if vel.length_squared() == 0:
            direction = Vector2(0, -1)
        else:
            direction = vel.normalize()
        size = agent.radius * 2
        perp = Vector2(-direction.y, direction.x)

        p1 = pos + direction * size
        p2 = pos - direction * size * 0.5 + perp * size * 0.5
        p3 = pos - direction * size * 0.5 - perp * size * 0.5

        points = [(p1.x, p1.y), (p2.x, p2.y), (p3.x, p3.y)]
        pygame.draw.polygon(self.screen, color, points)

    def _drawSpatialGrid(self) -> None:
        for col in range(self.grid.cols):
            x = col * self.grid.cellSize
            pygame.draw.line(self.screen, (60, 60, 60), (x, 0), (x, self.screenHeight))
        for row in range(self.grid.rows):
            y = row * self.grid.cellSize
            pygame.draw.line(self.screen, (60, 60, 60), (0, y), (self.screenWidth, y))

        # Draw agents in grid cells (optional debugging)
        for cell, agents in self.grid.grid.items():
            if not agents:
                continue
            col, row = cell
            x = col * self.grid.cellSize
            y = row * self.grid.cellSize
            pygame.draw.rect(self.screen, (80, 80, 80), (x, y, self.grid.cellSize, self.grid.cellSize), 1)
            # Draw count of agents in cell
            text = self.font.render(str(len(agents)), True, (200, 200, 200))
            self.screen.blit(text, (x + 2, y + 2))

    def _drawStats(self) -> None:
        texts = [
            f"FPS: {self.fps:.1f}",
            f"Agents: Boids={len(self.boids)} Predators={len(self.predators)} Leaders={len(self.leaders)} Obstacles={len(self.obstacles)}",
            f"Speed Multiplier: {self.speedMultiplier:.1f}",
            f"Grid Cells: {len(self.grid.grid)}",
            "Controls: [SPACE] Pause, [G] Toggle Grid, [V] Visualization Mode, [+/-] Speed, [H] Toggle Help, [ESC] Quit"
        ]
        if self.showHelp:
            y = 5
            for txt in texts:
                surf = self.font.render(txt, True, (230, 230, 230))
                self.screen.blit(surf, (5, y))
                y += 18

    def _measureFPS(self) -> None:
        self.frameCount += 1
        currentTime = time.time()
        elapsed = currentTime - self.lastFpsCheck
        if elapsed >= 1.0:
            self.fps = self.frameCount / elapsed
            self.fpsHistory.append(self.fps)
            if len(self.fpsHistory) > 100:
                self.fpsHistory.pop(0)
            self.frameCount = 0
            self.lastFpsCheck = currentTime

    def run(self, autoTestMode: bool = False) -> None:
        startTime = time.time()
        testStage = 0
        testStageTime = startTime
        testStageDuration = 10  # seconds per stage in autoTestMode
        acceleratedSpeed = 10.0

        try:
            while self.running:
                self._handleEvents()
                if not self.paused:
                    # Auto test mode sequence
                    if autoTestMode:
                        elapsedTotal = time.time() - startTime
                        if elapsedTotal >= 30:
                            # End auto test
                            break
                        # Stage management
                        elapsedStage = time.time() - testStageTime
                        if elapsedStage > testStageDuration:
                            testStage += 1
                            testStageTime = time.time()
                            if testStage > 2:
                                testStage = 0
                            # Mode switching for testing
                            if testStage == 0:
                                self._setTestScenarioFlocking()
                            elif testStage == 1:
                                self._setTestScenarioPredatorPrey()
                            elif testStage == 2:
                                self._setTestScenarioObstacles()
                        self.speedMultiplier = acceleratedSpeed

                    self._populateSpatialGrid()
                    self._updateAgents()

                self.screen.fill(self.backgroundColor)
                if self.visualizeGrid:
                    self._drawSpatialGrid()

                self._drawAgents()
                self._drawStats()

                pygame.display.flip()
                self._measureFPS()
                self.clock.tick(self.config.get("fpsTarget", 60) * self.speedMultiplier)

            if autoTestMode:
                print("BOIDS_SIMULATION_COMPLETE_SUCCESS")
        except Exception as e:
            print(f"Simulation error: {e}")
            raise
        finally:
            pygame.quit()

    # Auto test scenarios
    def _setTestScenarioFlocking(self) -> None:
        # Standard flocking: all agents active, no predators, no obstacles
        self.predators.clear()
        self.obstacles.clear()
        if len(self.boids) < 200:
            self._addBoids(200 - len(self.boids))
        if len(self.leaders) < 10:
            self._addLeaders(10 - len(self.leaders))
        # No obstacles or predators in this stage

    def _setTestScenarioPredatorPrey(self) -> None:
        # Predators active, some obstacles off
        if len(self.predators) < 10:
            self._addPredators(10 - len(self.predators))
        if len(self.obstacles) > 0:
            self.obstacles.clear()

    def _setTestScenarioObstacles(self) -> None:
        # Obstacles active, predators present
        if len(self.obstacles) < 20:
            self._addObstacles(20 - len(self.obstacles))
        if len(self.predators) < 10:
            self._addPredators(10 - len(self.predators))

    def _addBoids(self, count: int) -> None:
        for _ in range(count):
            pos = Vector2(np.random.uniform(0, self.screenWidth),
                          np.random.uniform(0, self.screenHeight))
            vel = Vector2(np.random.uniform(-1, 1), np.random.uniform(-1, 1))
            vel.scale_to_length(np.random.uniform(1.0, self.config.get("maxSpeed", 4.0)))
            b = Boid(pos, vel, self.config)
            self.boids.append(b)

    def _addPredators(self, count: int) -> None:
        for _ in range(count):
            pos = Vector2(np.random.uniform(0, self.screenWidth),
                          np.random.uniform(0, self.screenHeight))
            vel = Vector2(np.random.uniform(-1, 1), np.random.uniform(-1, 1))
            vel.scale_to_length(np.random.uniform(1.0, self.config.get("maxSpeed", 4.5)*1.2))
            p = Predator(pos, vel, self.config)
            self.predators.append(p)

    def _addObstacles(self, count: int) -> None:
        for _ in range(count):
            pos = Vector2(np.random.uniform(0, self.screenWidth),
                          np.random.uniform(0, self.screenHeight))
            r = np.random.uniform(10, 20)
            o = Obstacle(pos, r)
            self.obstacles.append(o)

    def _addLeaders(self, count: int) -> None:
        for _ in range(count):
            pos = Vector2(np.random.uniform(0, self.screenWidth),
                          np.random.uniform(0, self.screenHeight))
            vel = Vector2(np.random.uniform(-1, 1), np.random.uniform(-1, 1))
            vel.scale_to_length(np.random.uniform(1.0, self.config.get("maxSpeed", 4.0)))
            l = Leader(pos, vel, self.config)
            self.leaders.append(l)

# ==== Main Entry Point ====
def main() -> None:
    autoTestMode = False
    if '--auto-test' in sys.argv:
        autoTestMode = True

    config = ConfigManager()

    # Apply any command line config overrides here if needed
    sim = Simulation(config)
    sim.run(autoTestMode=autoTestMode)

    if autoTestMode:
        # Calculate and print scores
        scoreManager = sim.scoreManager
        # For demo purposes, assign some sample scores (should be from real tests)
        scoreManager.scores["flocking"] = 18
        scoreManager.scores["spatialHash"] = 14
        scoreManager.scores["obstacleAvoidance"] = 9
        scoreManager.scores["predatorPrey"] = 9
        scoreManager.scores["uiControls"] = 8
        # Approximate performance fps from sim
        fps = sim.fps or 60
        scoreManager.computePerformanceScore(fps, len(sim.boids) + len(sim.predators))
        scoreManager.scores["codeQuality"] = 8
        scoreManager.scores["documentation"] = 5
        scoreManager.scores["errorHandling"] = 5
        scoreManager.scores["testing"] = 4

        scoreManager.report()
        scoreManager.saveJsonReport(config.get("scoreOutputFile", "boids_simulation_score.json"))

if __name__ == "__main__":
    main()