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

Refactor EnergyAgent and EnergyModel classes

[pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

Refactor energy portrayal and model initialization

Updated agent portrayal logic to use LOW_ENERGY_THRESHOLD for energy levels. Refactored model initialization for easier parameter tweaking.

Fix Ruff lint: use lowercase parameter name for agent count

Update README and align parameter naming in app/model

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,35 @@
+from mesa.visualization import SolaraViz, make_space_component
+from model import EnergyModel
+
+
+def agent_portrayal(agent):
+    """Visual representation of agent based on energy level."""
+
+    if agent.energy > agent.LOW_ENERGY_THRESHOLD + 2:
+        color = "#2ecc71"  # high energy (green)
+    elif agent.energy > agent.LOW_ENERGY_THRESHOLD:
+        color = "#f1c40f"  # medium energy (yellow)
+    else:
+        color = "#e74c3c"  # low energy (red)
+
+    return {
+        "color": color,
+        "size": 40,
+    }
+
+
+# Allow easy parameter tweaking
+model = EnergyModel(
+    n=20,
+    width=10,
+    height=10,
+)
+
+page = SolaraViz(
+    model,
+    components=[
+        make_space_component(agent_portrayal),
+    ],
+)
+
+__all__ = ["page"]

examples/energy_expenditure/model.py

@@ -0,0 +1,70 @@
+from mesa import Agent, Model
+from mesa.space import MultiGrid
+
+
+class EnergyAgent(Agent):
+    # --- Tunable Parameters ---
+    LOW_ENERGY_THRESHOLD = 4
+    MOVE_DECAY = 1.0
+    REST_DECAY = 0.4
+
+    def __init__(self, model, energy=10):
+        super().__init__(model)
+        self.energy = energy
+        self.alive = True
+
+    def step(self):
+        if not self.alive:
+            return
+
+        is_resting = self.energy < self.LOW_ENERGY_THRESHOLD
+
+        if is_resting:
+            self.rest()
+            decay = self.REST_DECAY
+        else:
+            self.move()
+            decay = self.MOVE_DECAY
+
+        self.energy = max(self.energy - decay, 0)
+
+        if self.energy == 0:
+            self._die()
+
+    def move(self):
+        neighbors = self.model.grid.get_neighborhood(
+            self.pos, moore=True, include_center=False
+        )
+        if neighbors:
+            new_pos = self.random.choice(neighbors)
+            self.model.grid.move_agent(self, new_pos)
+
+    def rest(self):
+        pass
+
+    def _die(self):
+        self.alive = False
+        self.model.grid.remove_agent(self)
+        self.remove()  # deregisters from model AgentSet
+
+
+class EnergyModel(Model):
+    def __init__(self, n=10, width=10, height=10):
+        super().__init__()
+        self.num_agents = n
+        self.grid = MultiGrid(width, height, torus=True)
+
+        for _ in range(self.num_agents):
+            agent = EnergyAgent(self)
+            x = self.random.randrange(self.grid.width)
+            y = self.random.randrange(self.grid.height)
+            self.grid.place_agent(agent, (x, y))
+
+        self.running = True
+
+    def step(self):
+        # RandomActivation replacement in Mesa 3.x
+        self.agents.shuffle_do("step")
+
+        if len(self.agents) == 0:
+            self.running = False

examples/energy_expenditure/requirements.txt

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