Add new termite example

examples/termites/README.md

@@ -0,0 +1,47 @@
+# Termite WoodChip Behaviour
+This model simulates termites interacting with wood chips, inspired by the [NetLogo Termites model](https://ccl.northwestern.edu/netlogo/models/Termites). It explores emergent behavior in decentralized systems, demonstrating how simple agents (termites) collectively organize wood chips into piles without centralized coordination.
+
+## Summary
+
+
+In this simulation, multiple termite agents move randomly on a grid containing scattered wood chips. Each termite follows simple rules:
+
+1. Move randomly.
+2. If carrying a wood chip and encountering another, place the carried chip in a nearby empty space.
+3. If not carrying a chip and encountering one, pick it up.
+
+Over time, these simple interactions lead to the formation of wood chip piles, illustrating decentralized organization without a central coordinator.
+
+
+## Installation
+
+Make sure that you have installed the `latest` version of mesa i.e `3.2.0.dev0`
+
+## Usage
+
+To run the simulation:
+
+```bash
+solara run app.py
+```
+
+
+## Model Details
+
+### Agents
+
+- **Termite:** An agent that moves within the grid environment, capable of carrying a single wood chip at a time.
+
+### Environment
+
+- **Grid:** A two-dimensional toroidal grid where termites interacts with the wood chips. The toroidal nature means agents exiting one edge re-enter from the opposite edge,
+
+- **PropertyLayer:** A data structure overlaying the grid, storing  the presence of wood chips at each cell.
+
+## References
+
+- Wilensky, U. (1997). NetLogo Termites model. Center for Connected Learning and Computer-Based Modeling, Northwestern University, Evanston, IL. Available at: [NetLogo Termites Model](https://ccl.northwestern.edu/netlogo/models/Termites)
+---
+
+
+

examples/termites/agents.py

@@ -0,0 +1,61 @@
+from mesa.discrete_space import CellAgent
+
+
+class Termite(CellAgent):
+    """A Termite agent starts wandering randomly.
+    If it bumps into a wood chip, it finds a nearby empty space and puts its wood chip down.
+
+    Attributes:
+        hasWoodChip(bool): True if the agent is carrying a wood chip.
+    """
+
+    def __init__(self, model, cell):
+        """
+        Args:
+            model: The model instance.
+            cell: The startin cell (position) of the agent.
+        """
+        super().__init__(model)
+        self.cell = cell
+        self.hasWoodChip = False
+
+    def move(self):
+        # Move the agent to a random neighboring cell.
+        self.cell = self.cell.neighborhood.select_random_cell()
+
+    def step(self):
+        # Move to a random neighboring cell
+        self.move()
+
+        # Check if Woodchip is present on the cell
+        if self.cell.woodcell:
+            # Termite agnet is not carrying any woodchip
+            if not self.hasWoodChip:
+                # Pick up the woodchip
+                self.hasWoodChip = True
+                # Remove the wood chip from the cell
+                self.cell.woodcell = False
+            else:
+                """
+                Termite agent is already carrying a woodchip and has bumped into another wood chip
+                then search for a empty space (no agent and no woodcell) in it's neighbourhood and drop the wood chip
+                """
+                empty_cell_neighbors = [
+                    x for x in self.cell.neighborhood if x.is_empty and not x.woodcell
+                ]
+
+                if empty_cell_neighbors:
+                    # Moving to random empty cell
+                    self.cell = self.cell.random.choice(empty_cell_neighbors)
+                    # Drop the woodchip
+                    self.hasWoodChip = False
+                    self.cell.woodcell = True
+        else:
+            # Termite agent has a wood chip
+            if self.hasWoodChip:
+                # search for neighbors
+                wood_chip_neighbors = [x for x in self.cell.neighborhood if x.woodcell]
+                if wood_chip_neighbors:
+                    # drop the Wood chip
+                    self.hasWoodChip = False
+                    self.cell.woodcell = True

examples/termites/app.py

@@ -0,0 +1,64 @@
+from mesa.visualization import SolaraViz
+from mesa.visualization.components.matplotlib_components import make_mpl_space_component
+from model import TermiteModel
+
+wood_chip_portrayal = {
+    "woodcell": {
+        "color": "blue",
+        "alpha": 0.6,
+        "colorbar": False,
+        "vmin": 0,
+        "vmax": 2,
+    },
+}
+
+
+def agent_portrayal(agent):
+    return {"marker": ">", "color": "red" if agent.hasWoodChip else "black", "size": 10}
+
+
+model_params = {
+    "num_termites": {
+        "type": "SliderInt",
+        "value": 50,
+        "label": "No. of Termites",
+        "min": 10,
+        "max": 100,
+        "step": 1,
+    },
+    "wood_chip_density": {
+        "type": "SliderFloat",
+        "value": 0.1,
+        "label": "Wood Chip Density",
+        "min": 0.01,
+        "max": 1,
+        "step": 0.1,
+    },
+    "width": 60,
+    "height": 60,
+}
+
+model = TermiteModel(num_termites=400, width=100, height=100, wood_chip_density=0.1)
+
+
+def post_process(ax):
+    ax.set_aspect("equal")
+    ax.set_xticks([])
+    ax.set_yticks([])
+
+
+woodchips_space = make_mpl_space_component(
+    agent_portrayal=agent_portrayal,
+    propertylayer_portrayal=wood_chip_portrayal,
+    post_process=post_process,
+    draw_grid=False,
+)
+
+page = SolaraViz(
+    model,
+    components=[woodchips_space],
+    model_params=model_params,
+    name="Termites Model",
+    play_interval=1,
+    render_interval=15,
+)

examples/termites/model.py

@@ -0,0 +1,51 @@
+import numpy as np
+from agents import Termite
+from mesa import Model
+from mesa.discrete_space import OrthogonalMooreGrid, PropertyLayer
+
+
+class TermiteModel(Model):
+    """
+    A simulation that depicts behavior of termite agents gathering wood chips into piles.
+    """
+
+    def __init__(
+        self, num_termites=50, width=60, height=60, wood_chip_density=0.4, seed=None
+    ):
+        """Initialize the model.
+
+        Args:
+            num_termites: Number of Termite Agents,
+            width: Grid width.
+            height: Grid heights.
+            wood_chip_density: Density of wood chips in the grid.
+        """
+        super().__init__(seed=seed)
+        self.num_termites = num_termites
+        self.wood_chip_density = wood_chip_density
+
+        # Initializing a OrthogonalMooreGrid: each cell has 8 neighbors
+        self.grid = OrthogonalMooreGrid((width, height), torus=True)
+
+        # Initializing up a PropertyLayer(woodcell) for wood_chips
+        self.wood_chips_layer = PropertyLayer(
+            "woodcell", (width, height), default_value=False, dtype=bool
+        )
+        self.wood_chips_layer.data = np.random.choice(
+            [True, False],
+            size=(width, height),
+            p=[self.wood_chip_density, 1 - self.wood_chip_density],
+        )
+
+        # Adding PropertyLayer to the grid"""
+        self.grid.add_property_layer(self.wood_chips_layer)
+
+        # Creating and adding termite agents to the grid
+        Termite.create_agents(
+            self,
+            self.num_termites,
+            self.random.sample(self.grid.all_cells.cells, k=self.num_termites),
+        )
+
+    def step(self):
+        self.agents.shuffle_do("step")