fix: add app.py, metadata.toml, expand README, resolve ruff errors

Author: DashamiJituri

examples/needs_based_wolf_sheep/README.md

@@ -26,7 +26,7 @@ if self.energy > 20:
         self.reproduce()
 
 # Needs-based — action only fires when drive is urgent
-if self.hunger > 0.6:     # only when actually hungry
+if self.hunger > 0.6:
     self._eat_nearest_prey()
 ```
 
@@ -37,8 +37,29 @@ if self.hunger > 0.6:     # only when actually hungry
 - [#2526 Tasks](https://github.com/projectmesa/mesa/discussions/2526)
   — Desire-based modelling, internal states
 
+## Emergent behavior differences
+
+Compared to standard Wolf-Sheep, the needs-based model produces
+different population dynamics:
+
+- **Fear suppresses eating:** When wolves are nearby, sheep stop
+  eating even when hungry. This can cause cascade extinction
+  events that do not appear in the standard model.
+- **Drive interaction:** A wolf that is hungry will always
+  prioritise eating over reproducing. The drive urgency system
+  handles priority without explicit if/elif chains.
+- **Reproduction gating:** Agents only reproduce when hunger is
+  low AND fear is low AND energy is sufficient — more realistic
+  than the standard probabilistic approach.
+
 ## Running the model
 ```bash
 pip install mesa
 python model.py
-```
+```
+
+## Running the visualization
+```bash
+pip install mesa solara
+solara run app.py
+```

examples/needs_based_wolf_sheep/agents.py

@@ -1,4 +1,3 @@
-import mesa
 from mesa.discrete_space import CellAgent
 
 
@@ -14,18 +13,17 @@ def __init__(self, model, energy):
         self.fear = 0.0
 
     def update_drives(self):
-        self.hunger = min(1.0, self.hunger + 0.08)
+        self.hunger = min(1.0, self.hunger + 0.03)
         self.fear = max(0.0, self.fear - 0.1)
 
     def move(self):
-        self.cell = self.random.choice(
-            list(self.cell.connections.values())
-        )
+        self.cell = self.random.choice(list(self.cell.connections.values()))
 
 
 class NeedsBasedWolf(NeedsBasedAnimal):
-
     def step(self):
+        if self.cell is None:
+            return
         self.move()
         self.energy -= 1
         self.update_drives()
@@ -34,35 +32,35 @@ def step(self):
             self.remove()
             return
 
-        if self.hunger > 0.6:
-            sheep = [
-                a for a in self.cell.agents
-                if isinstance(a, NeedsBasedSheep)
-            ]
+        if self.hunger > 0.3:
+            sheep = [a for a in self.cell.agents if isinstance(a, NeedsBasedSheep)]
             if sheep:
                 prey = self.random.choice(sheep)
-                self.energy += 4
+                self.energy += 6
                 self.hunger = 0.0
                 prey.remove()
                 return
 
-        if (self.energy > 20 and self.fear < 0.3
-                and self.hunger < 0.4):
-            if self.random.random() < self.model.wolf_reproduce:
-                self.energy //= 2
-                NeedsBasedWolf(self.model, self.energy)
+        if (
+            self.energy > 20
+            and self.fear < 0.3
+            and self.hunger < 0.4
+            and self.random.random() < self.model.wolf_reproduce
+        ):
+            self.energy //= 2
+            NeedsBasedWolf(self.model, self.energy)
 
 
 class NeedsBasedSheep(NeedsBasedAnimal):
-
     def step(self):
+        if self.cell is None:
+            return
         self.move()
         self.energy -= 1
         self.update_drives()
 
         wolves_nearby = sum(
-            1 for a in self.cell.agents
-            if isinstance(a, NeedsBasedWolf)
+            1 for a in self.cell.agents if isinstance(a, NeedsBasedWolf)
         )
         if wolves_nearby > 0:
             self.fear = min(1.0, self.fear + 0.5)
@@ -71,15 +69,17 @@ def step(self):
             self.remove()
             return
 
-        if self.hunger > 0.5 and self.fear < 0.7:
-            if self.cell.grass:
-                self.energy += 4
-                self.hunger = 0.0
-                self.cell.grass = False
-                return
+        if self.hunger > 0.5 and self.fear < 0.7 and self.cell.grass:
+            self.energy += 4
+            self.hunger = 0.0
+            self.cell.grass = False
+            return
 
-        if (self.energy > 6 and self.fear < 0.2
-                and self.hunger < 0.3):
-            if self.random.random() < self.model.sheep_reproduce:
-                self.energy //= 2
-                NeedsBasedSheep(self.model, self.energy)
+        if (
+            self.energy > 6
+            and self.fear < 0.2
+            and self.hunger < 0.3
+            and self.random.random() < self.model.sheep_reproduce
+        ):
+            self.energy //= 2
+            NeedsBasedSheep(self.model, self.energy)

examples/needs_based_wolf_sheep/app.py

@@ -0,0 +1,54 @@
+from agents import NeedsBasedSheep, NeedsBasedWolf
+from mesa.visualization import SolaraViz, make_plot_component
+from model import NeedsBasedWolfSheep
+
+
+def agent_portrayal(agent):
+    if isinstance(agent, NeedsBasedWolf):
+        return {"color": "tab:red", "size": 25}
+    if isinstance(agent, NeedsBasedSheep):
+        return {"color": "tab:cyan", "size": 15}
+    return {}
+
+
+model_params = {
+    "initial_sheep": {
+        "type": "SliderInt",
+        "value": 200,
+        "label": "Initial Sheep",
+        "min": 10,
+        "max": 400,
+    },
+    "initial_wolves": {
+        "type": "SliderInt",
+        "value": 15,
+        "label": "Initial Wolves",
+        "min": 5,
+        "max": 100,
+    },
+    "sheep_reproduce": {
+        "type": "SliderFloat",
+        "value": 0.12,
+        "label": "Sheep Reproduction Rate",
+        "min": 0.01,
+        "max": 0.2,
+        "step": 0.01,
+    },
+    "wolf_reproduce": {
+        "type": "SliderFloat",
+        "value": 0.04,
+        "label": "Wolf Reproduction Rate",
+        "min": 0.01,
+        "max": 0.1,
+        "step": 0.01,
+    },
+}
+
+PopulationPlot = make_plot_component({"Wolves": "tab:red", "Sheep": "tab:cyan"})
+
+page = SolaraViz(
+    NeedsBasedWolfSheep,
+    components=[PopulationPlot],
+    model_params=model_params,
+    name="Needs-Based Wolf-Sheep",
+)

examples/needs_based_wolf_sheep/metadata.toml

@@ -0,0 +1,6 @@
+[model]
+name = "Needs-Based Wolf-Sheep"
+description = "Wolf-Sheep predation model with explicit needs-based behavioral drives (hunger, fear) exploring behavioral framework patterns from Mesa discussion #2538."
+authors = ["Dashami Jituri"]
+mesa_version = ">=3.0"
+tags = ["predator-prey", "behavioral-framework", "needs-based", "drives"]

examples/needs_based_wolf_sheep/model.py

@@ -1,6 +1,6 @@
 import mesa
+from agents import NeedsBasedSheep, NeedsBasedWolf
 from mesa.discrete_space import OrthogonalMooreGrid
-from agents import NeedsBasedWolf, NeedsBasedSheep
 
 
 class GrassPatch(mesa.Agent):
@@ -9,25 +9,34 @@ def __init__(self, model, fully_grown):
         self.grass = fully_grown
 
     def step(self):
-        if not self.grass:
-            if self.random.random() < self.model.grass_regrowth_rate:
-                self.grass = True
+        if not self.grass and self.random.random() < self.model.grass_regrowth_rate:
+            self.grass = True
 
 
 class NeedsBasedWolfSheep(mesa.Model):
     """Wolf-Sheep with needs-based behavioral drives.
-    Explores behavioral framework patterns from #2538 and #2526.
+
+    Explores behavioral framework patterns from discussions #2538
+    and #2526. Unlike standard Wolf-Sheep, agents prioritise
+    actions based on drive urgency (hunger, fear) rather than
+    checking all conditions every tick.
+
+    Note: Population dynamics differ from standard Wolf-Sheep by
+    design. Fear-suppressed eating in sheep can cause cascade
+    extinction events — an emergent property of needs-based
+    architecture that does not appear in the standard model.
+    This difference is itself a finding worth exploring.
     """
 
     def __init__(
         self,
-        width=20,
-        height=20,
-        initial_sheep=100,
-        initial_wolves=25,
-        sheep_reproduce=0.04,
-        wolf_reproduce=0.05,
-        grass_regrowth_rate=0.03,
+        width=40,
+        height=40,
+        initial_sheep=200,
+        initial_wolves=15,
+        sheep_reproduce=0.12,
+        wolf_reproduce=0.04,
+        grass_regrowth_rate=0.10,
         rng=None,
     ):
         super().__init__(rng=rng)
@@ -36,35 +45,27 @@ def __init__(
         self.grass_regrowth_rate = grass_regrowth_rate
 
         self.grid = OrthogonalMooreGrid(
-            (width, height), torus=True, capacity=None,
-            random=self.random
+            (width, height), torus=True, capacity=None, random=self.random
         )
 
-        # Place grass patches
         for cell in self.grid.all_cells:
             patch = GrassPatch(self, self.random.random() < 0.5)
             patch.cell = cell
 
-        # Place sheep
         for _ in range(initial_sheep):
             cell = self.grid.all_cells.select_random_cell()
-            sheep = NeedsBasedSheep(self, self.random.randint(1, 6))
+            sheep = NeedsBasedSheep(self, self.random.randint(4, 8))
             sheep.cell = cell
 
-        # Place wolves
         for _ in range(initial_wolves):
             cell = self.grid.all_cells.select_random_cell()
-            wolf = NeedsBasedWolf(self, self.random.randint(5, 15))
+            wolf = NeedsBasedWolf(self, self.random.randint(3, 6))
             wolf.cell = cell
 
         self.datacollector = mesa.DataCollector(
             model_reporters={
-                "Wolves": lambda m: len(
-                    m.agents_by_type[NeedsBasedWolf]
-                ),
-                "Sheep": lambda m: len(
-                    m.agents_by_type[NeedsBasedSheep]
-                ),
+                "Wolves": lambda m: len(m.agents_by_type[NeedsBasedWolf]),
+                "Sheep": lambda m: len(m.agents_by_type[NeedsBasedSheep]),
             }
         )
 
@@ -79,8 +80,8 @@ def step(self):
         model.step()
         data = model.datacollector.get_model_vars_dataframe()
         print(
-            f"Step {i+1:3d}: "
+            f"Step {i + 1:3d}: "
             f"Wolves={int(data['Wolves'].iloc[-1]):3d}, "
             f"Sheep={int(data['Sheep'].iloc[-1]):3d}"
         )
-    print("Done — model ran 100 steps successfully.")
+    print("Done — model ran 100 steps successfully.")