Add energy expenditure example demonstrating state-based agent behavior (fixes #446)

Author: nyksans

examples/energy_expenditure/README.md

@@ -0,0 +1,43 @@
+# Energy Expenditure
+
+This example explores a simple question:
+
+> How do agents survive when every action costs energy?
+
+Each agent has a limited internal energy that decreases over time.
+They must balance between moving (which helps exploration but costs energy) and resting (which recovers energy slowly).
+
+## Model Behavior
+
+- Every step reduces energy
+- Moving costs additional energy
+- Resting allows partial recovery
+- Agents are removed when their energy reaches zero
+
+## What to Observe
+
+When you run the model:
+
+- Agents initially move actively across the grid
+- Over time, movement slows as energy drops
+- The population gradually decreases
+- Some agents survive longer by conserving energy
+
+This creates a simple but meaningful trade-off between activity and survival.
+
+## Why this example
+
+This model demonstrates **state-driven behavior**, where decisions are based on an agent's internal condition rather than randomness.
+
+It serves as a minimal foundation for:
+
+- resource-based simulations
+- survival dynamics
+- adaptive agent behavior
+
+## Run the model
+
+```bash
+pip install -r requirements.txt
+solara run app.py
+```

examples/energy_expenditure/app.py

@@ -0,0 +1,29 @@
+from mesa.visualization import SolaraViz, make_space_component
+from model import EnergyExpenditureModel
+
+
+def agent_portrayal(agent):
+    if agent.energy > 6:
+        color = "#2ecc71"
+    elif agent.energy > 3:
+        color = "#f1c40f"
+    else:
+        color = "#e74c3c"
+
+    return {
+        "color": color,
+        "size": 40,
+    }
+
+
+model = EnergyExpenditureModel()
+
+page = SolaraViz(
+    model,
+    components=[
+        make_space_component(agent_portrayal),
+    ],
+)
+
+# Required for Solara to detect the app
+__all__ = ["page"]

examples/energy_expenditure/model.py

@@ -0,0 +1,99 @@
+import random
+
+from mesa import Agent, Model
+from mesa.space import MultiGrid
+
+
+class EnergyAgent(Agent):
+    """
+    Agent that balances movement and survival based on internal energy.
+    """
+
+    LOW_ENERGY_THRESHOLD = 4
+
+    def __init__(self, model, unique_id):
+        super().__init__(model)
+
+        # Store ID locally (compatible with this Mesa version)
+        self.id = unique_id
+
+        # Initialize energy from model-defined range
+        self.energy = random.randint(*self.model.initial_energy_range)
+
+    def step(self):
+        """Execute one step of agent behavior."""
+
+        # Base energy decay
+        self.energy -= 1
+        self.energy = max(self.energy, 0)
+
+        if self.energy == 0:
+            self.die()
+            return
+
+        # Decision based on energy level
+        if self.energy < self.LOW_ENERGY_THRESHOLD:
+            self.rest()
+        else:
+            self.move()
+
+    def move(self):
+        """Move to a neighboring cell (costs extra energy)."""
+
+        # Movement cost
+        self.energy -= 1
+        self.energy = max(self.energy, 0)
+
+        neighbors = self.model.grid.get_neighborhood(
+            self.pos, moore=True, include_center=False
+        )
+
+        if neighbors:
+            new_pos = random.choice(neighbors)
+            self.model.grid.move_agent(self, new_pos)
+
+    def rest(self):
+        """Recover energy slowly."""
+        self.energy += 1
+
+    def die(self):
+        """Safely remove agent from grid and model."""
+        self.model.grid.remove_agent(self)
+        self.model.remove_agent(self)
+
+
+class EnergyExpenditureModel(Model):
+    """
+    Model representing agents constrained by energy expenditure.
+    """
+
+    def __init__(self, n_agents=20, width=15, height=15):
+        super().__init__()
+
+        # Define energy initialization range (removes magic numbers)
+        self.initial_energy_range = (6, 12)
+
+        # Create toroidal grid
+        self.grid = MultiGrid(width, height, torus=True)
+
+        # Internal agent storage (safe iteration control)
+        self.agents_list = []
+
+        # Create and place agents
+        for i in range(n_agents):
+            agent = EnergyAgent(self, i)
+            self.agents_list.append(agent)
+
+            x = self.random.randrange(width)
+            y = self.random.randrange(height)
+            self.grid.place_agent(agent, (x, y))
+
+    def step(self):
+        """Advance the model by one step."""
+        for agent in list(self.agents_list):
+            agent.step()
+
+    def remove_agent(self, agent):
+        """Remove agent from internal tracking."""
+        if agent in self.agents_list:
+            self.agents_list.remove(agent)

examples/energy_expenditure/requirements.txt

@@ -0,0 +1,2 @@
+mesa[viz]
+matplotlib