Mesa 2.4.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

mesa/examples/advanced/sugarscape_g1mt/model.py

@@ -0,0 +1,180 @@
+from pathlib import Path
+
+import numpy as np
+
+import mesa
+from mesa.examples.advanced.sugarscape_g1mt.agents import Resource, Trader
+from mesa.experimental.cell_space import OrthogonalVonNeumannGrid
+
+
+# Helper Functions
+def flatten(list_of_lists):
+    """
+    helper function for model datacollector for trade price
+    collapses agent price list into one list
+    """
+    return [item for sublist in list_of_lists for item in sublist]
+
+
+def geometric_mean(list_of_prices):
+    """
+    find the geometric mean of a list of prices
+    """
+    return np.exp(np.log(list_of_prices).mean())
+
+
+def get_trade(agent):
+    """
+    For agent reporters in data collector
+
+    return list of trade partners and None for other agents
+    """
+    if isinstance(agent, Trader):
+        return agent.trade_partners
+    else:
+        return None
+
+
+class SugarscapeG1mt(mesa.Model):
+    """
+    Manager class to run Sugarscape with Traders
+    """
+
+    def __init__(
+        self,
+        width=50,
+        height=50,
+        initial_population=200,
+        endowment_min=25,
+        endowment_max=50,
+        metabolism_min=1,
+        metabolism_max=5,
+        vision_min=1,
+        vision_max=5,
+        enable_trade=True,
+        seed=None,
+    ):
+        super().__init__(seed=seed)
+        # Initiate width and height of sugarscape
+        self.width = width
+        self.height = height
+        # Initiate population attributes
+        self.initial_population = initial_population
+        self.endowment_min = endowment_min
+        self.endowment_max = endowment_max
+        self.metabolism_min = metabolism_min
+        self.metabolism_max = metabolism_max
+        self.vision_min = vision_min
+        self.vision_max = vision_max
+        self.enable_trade = enable_trade
+        self.running = True
+
+        # initiate mesa grid class
+        self.grid = OrthogonalVonNeumannGrid((self.width, self.height), torus=False)
+        # initiate datacollector
+        self.datacollector = mesa.DataCollector(
+            model_reporters={
+                "Trader": lambda m: len(m.agents_by_type[Trader]),
+                "Trade Volume": lambda m: sum(
+                    len(a.trade_partners) for a in m.agents_by_type[Trader]
+                ),
+                "Price": lambda m: geometric_mean(
+                    flatten([a.prices for a in m.agents_by_type[Trader]])
+                ),
+            },
+            agent_reporters={"Trade Network": lambda a: get_trade(a)},
+        )
+
+        # read in landscape file from supplmentary material
+        sugar_distribution = np.genfromtxt(Path(__file__).parent / "sugar-map.txt")
+        spice_distribution = np.flip(sugar_distribution, 1)
+
+        for cell in self.grid.all_cells:
+            max_sugar = sugar_distribution[cell.coordinate]
+            max_spice = spice_distribution[cell.coordinate]
+            Resource(self, max_sugar, max_spice, cell)
+
+        for _ in range(self.initial_population):
+            # get agent position
+            x = self.random.randrange(self.width)
+            y = self.random.randrange(self.height)
+            # see Growing Artificial Societies p. 108 for initialization
+            # give agents initial endowment
+            sugar = int(self.random.uniform(self.endowment_min, self.endowment_max + 1))
+            spice = int(self.random.uniform(self.endowment_min, self.endowment_max + 1))
+            # give agents initial metabolism
+            metabolism_sugar = int(
+                self.random.uniform(self.metabolism_min, self.metabolism_max + 1)
+            )
+            metabolism_spice = int(
+                self.random.uniform(self.metabolism_min, self.metabolism_max + 1)
+            )
+            # give agents vision
+            vision = int(self.random.uniform(self.vision_min, self.vision_max + 1))
+
+            cell = self.grid[(x, y)]
+            # create Trader object
+            Trader(
+                self,
+                cell,
+                sugar=sugar,
+                spice=spice,
+                metabolism_sugar=metabolism_sugar,
+                metabolism_spice=metabolism_spice,
+                vision=vision,
+            )
+
+    def step(self):
+        """
+        Unique step function that does staged activation of sugar and spice
+        and then randomly activates traders
+        """
+        # step Resource agents
+        self.agents_by_type[Resource].do("step")
+
+        # step trader agents
+        # to account for agent death and removal we need a separate data structure to
+        # iterate
+        trader_shuffle = self.agents_by_type[Trader].shuffle()
+
+        for agent in trader_shuffle:
+            agent.prices = []
+            agent.trade_partners = []
+            agent.move()
+            agent.eat()
+            agent.maybe_die()
+
+        if not self.enable_trade:
+            # If trade is not enabled, return early
+            self.datacollector.collect(self)
+            return
+
+        trader_shuffle = self.agents_by_type[Trader].shuffle()
+
+        for agent in trader_shuffle:
+            agent.trade_with_neighbors()
+
+        # collect model level data
+        self.datacollector.collect(self)
+        """
+        Mesa is working on updating datacollector agent reporter
+        so it can collect information on specific agents from
+        mesa.time.RandomActivationByType.
+
+        Please see issue #1419 at
+        https://github.com/projectmesa/mesa/issues/1419
+        (contributions welcome)
+
+        Below is one way to update agent_records to get specific Trader agent data
+        """
+        # Need to remove excess data
+        # Create local variable to store trade data
+        agent_trades = self.datacollector._agent_records[self.steps]
+        # Get rid of all None to reduce data storage needs
+        agent_trades = [agent for agent in agent_trades if agent[2] is not None]
+        # Reassign the dictionary value with lean trade data
+        self.datacollector._agent_records[self.steps] = agent_trades
+
+    def run_model(self, step_count=1000):
+        for _ in range(step_count):
+            self.step()

mesa/examples/advanced/sugarscape_g1mt/sugar-map.txt

@@ -0,0 +1,50 @@
+0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 3 3 3 3 3 3 2 2 2 2 2 2 2 2
+0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 3 3 3 3 3 3 3 3 3 3 2 2 2 2 2 2
+0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 3 3 3 3 3 3 3 3 3 3 3 3 3 3 2 2 2 2
+0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 2 2 2 2 2 2 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 2 2 2
+0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 2 2 2 2 2 2 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 2 2
+0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 2 2 2 2 2 2 3 3 3 3 3 3 3 4 4 4 4 3 3 3 3 3 3 3 2 2
+0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 2 2 2 2 2 3 3 3 3 3 3 4 4 4 4 4 4 4 4 3 3 3 3 3 3 2
+0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 2 2 2 2 2 2 3 3 3 3 3 4 4 4 4 4 4 4 4 4 4 3 3 3 3 3 2
+0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 2 2 2 2 2 3 3 3 3 3 3 4 4 4 4 4 4 4 4 4 4 3 3 3 3 3 3
+0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 3 3 3 3 3 4 4 4 4 4 4 4 4 4 4 4 4 3 3 3 3 3
+0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 3 3 3 3 3 4 4 4 4 4 4 4 4 4 4 4 4 3 3 3 3 3
+0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 3 3 3 3 3 4 4 4 4 4 4 4 4 4 4 4 4 3 3 3 3 3
+0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 3 3 3 3 3 4 4 4 4 4 4 4 4 4 4 4 4 3 3 3 3 3
+0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 3 3 3 3 3 3 4 4 4 4 4 4 4 4 4 4 3 3 3 3 3 3
+0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 3 3 3 3 3 3 4 4 4 4 4 4 4 4 4 4 3 3 3 3 3 2
+0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 3 3 3 3 3 3 3 4 4 4 4 4 4 4 4 3 3 3 3 3 3 2
+1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 3 3 3 3 3 3 3 3 3 4 4 4 4 3 3 3 3 3 3 3 2 2
+1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 2 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 2 2
+1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 2 2 2 2 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 2 2 2
+1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 2 2 2 2
+1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 3 3 3 3 3 3 3 3 3 3 3 3 3 2 2 2 2 2 2
+1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 3 3 3 3 3 3 3 3 3 2 2 2 2 2 2 2 2
+1 1 1 1 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 1
+1 1 1 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 1 1
+1 1 2 2 2 2 2 2 2 2 2 2 3 3 3 3 3 3 3 3 3 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 1 1 1
+1 2 2 2 2 2 2 2 2 2 3 3 3 3 3 3 3 3 3 3 3 3 3 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1
+1 2 2 2 2 2 2 2 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1
+2 2 2 2 2 2 2 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 2 2 2 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 1 1
+2 2 2 2 2 2 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 2 2 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 1 1 1
+2 2 2 2 2 2 3 3 3 3 3 3 3 4 4 4 4 3 3 3 3 3 3 3 3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 1 1 1 1
+2 2 2 2 2 3 3 3 3 3 3 4 4 4 4 4 4 4 4 3 3 3 3 3 3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 1 0 0 0
+2 2 2 2 2 3 3 3 3 3 4 4 4 4 4 4 4 4 4 4 3 3 3 3 3 3 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0
+2 2 2 2 3 3 3 3 3 3 4 4 4 4 4 4 4 4 4 4 3 3 3 3 3 3 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0
+2 2 2 2 3 3 3 3 3 4 4 4 4 4 4 4 4 4 4 4 4 3 3 3 3 3 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0
+2 2 2 2 3 3 3 3 3 4 4 4 4 4 4 4 4 4 4 4 4 3 3 3 3 3 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0
+2 2 2 2 3 3 3 3 3 4 4 4 4 4 4 4 4 4 4 4 4 3 3 3 3 3 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0
+2 2 2 2 3 3 3 3 3 4 4 4 4 4 4 4 4 4 4 4 4 3 3 3 3 3 2 2 2 2 2 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0
+2 2 2 2 3 3 3 3 3 3 4 4 4 4 4 4 4 4 4 4 3 3 3 3 3 3 2 2 2 2 2 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0
+2 2 2 2 2 3 3 3 3 3 4 4 4 4 4 4 4 4 4 4 3 3 3 3 3 2 2 2 2 2 2 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0
+2 2 2 2 2 3 3 3 3 3 3 4 4 4 4 4 4 4 4 3 3 3 3 3 3 2 2 2 2 2 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0
+2 2 2 2 2 2 3 3 3 3 3 3 3 4 4 4 4 3 3 3 3 3 3 3 2 2 2 2 2 2 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0
+2 2 2 2 2 2 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 2 2 2 2 2 2 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0
+2 2 2 2 2 2 2 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 2 2 2 2 2 2 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0
+1 2 2 2 2 2 2 2 3 3 3 3 3 3 3 3 3 3 3 3 3 3 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0
+1 2 2 2 2 2 2 2 2 2 3 3 3 3 3 3 3 3 3 3 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0
+1 1 2 2 2 2 2 2 2 2 2 2 3 3 3 3 3 3 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0
+1 1 1 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0
+1 1 1 1 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0
+1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0
+1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0

mesa/examples/advanced/sugarscape_g1mt/tests.py

@@ -0,0 +1,69 @@
+import numpy as np
+from scipy import stats
+
+from .agents import Trader
+from .model import SugarscapeG1mt, flatten
+
+
+def check_slope(y, increasing):
+    x = range(len(y))
+    slope, intercept, _, p_value, _ = stats.linregress(x, y)
+    result = (slope > 0) if increasing else (slope < 0)
+    # p_value for significance.
+    assert result and p_value < 0.05, (slope, p_value)
+
+
+def test_decreasing_price_variance():
+    # The variance of the average trade price should decrease over time (figure IV-3)
+    # See Growing Artificial Societies p. 109.
+    model = SugarscapeG1mt(42)
+    model.datacollector._new_model_reporter(
+        "price_variance",
+        lambda m: np.var(
+            flatten([a.prices for a in m.agents_by_type[Trader].values()])
+        ),
+    )
+    model.run_model(step_count=50)
+
+    df_model = model.datacollector.get_model_vars_dataframe()
+
+    check_slope(df_model.price_variance, increasing=False)
+
+
+def test_carrying_capacity():
+    def calculate_carrying_capacities(enable_trade):
+        carrying_capacities = []
+        visions = range(1, 10)
+        for vision_max in visions:
+            model = SugarscapeG1mt(vision_max=vision_max, enable_trade=enable_trade)
+            model.run_model(step_count=50)
+            carrying_capacities.append(len(model.agents_by_type[Trader]))
+        return carrying_capacities
+
+    # Carrying capacity should increase over mean vision (figure IV-6).
+    # See Growing Artificial Societies p. 112.
+    carrying_capacities_with_trade = calculate_carrying_capacities(True)
+    check_slope(
+        carrying_capacities_with_trade,
+        increasing=True,
+    )
+    # Carrying capacity should be higher when trade is enabled (figure IV-6).
+    carrying_capacities_no_trade = calculate_carrying_capacities(False)
+    check_slope(
+        carrying_capacities_no_trade,
+        increasing=True,
+    )
+
+    t_statistic, p_value = stats.ttest_rel(
+        carrying_capacities_with_trade, carrying_capacities_no_trade
+    )
+    # t_statistic > 0 means carrying_capacities_with_trade has larger values
+    # than carrying_capacities_no_trade.
+    # p_value for significance.
+    assert t_statistic > 0 and p_value < 0.05
+
+
+# TODO:
+# 1. Reproduce figure IV-12 that the log of average price should decrease over average agent age
+# 2. Reproduce figure IV-13 that the gini coefficient on trade should decrease over mean vision, and should be higher with trade
+# 3. a stricter test would be to ensure the amount of variance of the trade price matches figure IV-3

mesa/examples/advanced/wolf_sheep/Readme.md

@@ -0,0 +1,57 @@
+# Wolf-Sheep Predation Model
+
+## Summary
+
+A simple ecological model, consisting of three agent types: wolves, sheep, and grass. The wolves and the sheep wander around the grid at random. Wolves and sheep both expend energy moving around, and replenish it by eating. Sheep eat grass, and wolves eat sheep if they end up on the same grid cell.
+
+If wolves and sheep have enough energy, they reproduce, creating a new wolf or sheep (in this simplified model, only one parent is needed for reproduction). The grass on each cell regrows at a constant rate. If any wolves and sheep run out of energy, they die.
+
+The model is tests and demonstrates several Mesa concepts and features:
+ - MultiGrid
+ - Multiple agent types (wolves, sheep, grass)
+ - Overlay arbitrary text (wolf's energy) on agent's shapes while drawing on CanvasGrid
+ - Agents inheriting a behavior (random movement) from an abstract parent
+ - Writing a model composed of multiple files.
+ - Dynamically adding and removing agents from the schedule
+
+## Installation
+
+To install the dependencies use pip and the requirements.txt in this directory. e.g.
+
+```
+    # First, we clone the Mesa repo
+    $ git clone https://github.com/projectmesa/mesa.git
+    $ cd mesa
+    # Then we cd to the example directory
+    $ cd examples/wolf_sheep
+    $ pip install -r requirements.txt
+```
+
+## How to Run
+
+To run the model interactively, run ``mesa runserver`` in this directory. e.g.
+
+```
+    $ mesa runserver
+```
+
+Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press Reset, then Run.
+
+## Files
+
+* ``wolf_sheep/random_walk.py``: This defines the ``RandomWalker`` agent, which implements the behavior of moving randomly across a grid, one cell at a time. Both the Wolf and Sheep agents will inherit from it.
+* ``wolf_sheep/test_random_walk.py``: Defines a simple model and a text-only visualization intended to make sure the RandomWalk class was working as expected. This doesn't actually model anything, but serves as an ad-hoc unit test. To run it, ``cd`` into the ``wolf_sheep`` directory and run ``python test_random_walk.py``. You'll see a series of ASCII grids, one per model step, with each cell showing a count of the number of agents in it.
+* ``wolf_sheep/agents.py``: Defines the Wolf, Sheep, and GrassPatch agent classes.
+* ``wolf_sheep/scheduler.py``: Defines a custom variant on the RandomActivationByType scheduler, where we can define filters for the `get_type_count` function.
+* ``wolf_sheep/model.py``: Defines the Wolf-Sheep Predation model itself
+* ``wolf_sheep/server.py``: Sets up the interactive visualization server
+* ``run.py``: Launches a model visualization server.
+
+## Further Reading
+
+This model is closely based on the NetLogo Wolf-Sheep Predation Model:
+
+Wilensky, U. (1997). NetLogo Wolf Sheep Predation model. http://ccl.northwestern.edu/netlogo/models/WolfSheepPredation. Center for Connected Learning and Computer-Based Modeling, Northwestern University, Evanston, IL.
+
+See also the [Lotka–Volterra equations
+](https://en.wikipedia.org/wiki/Lotka%E2%80%93Volterra_equations) for an example of a classic differential-equation model with similar dynamics.

mesa/examples/advanced/wolf_sheep/agents.py

@@ -0,0 +1,102 @@
+from mesa.experimental.cell_space import CellAgent, FixedAgent
+
+
+class Animal(CellAgent):
+    """The base animal class."""
+
+    def __init__(self, model, energy, p_reproduce, energy_from_food, cell):
+        """Initializes an animal.
+
+        Args:
+            model: a model instance
+            energy: starting amount of energy
+            p_reproduce: probability of sexless reproduction
+            energy_from_food: energy obtained from 1 unit of food
+            cell: the cell in which the animal starts
+        """
+        super().__init__(model)
+        self.energy = energy
+        self.p_reproduce = p_reproduce
+        self.energy_from_food = energy_from_food
+        self.cell = cell
+
+    def spawn_offspring(self):
+        """Create offspring."""
+        self.energy /= 2
+        self.__class__(
+            self.model,
+            self.energy,
+            self.p_reproduce,
+            self.energy_from_food,
+            self.cell,
+        )
+
+    def feed(self): ...
+
+    def step(self):
+        """One step of the agent."""
+        self.cell = self.cell.neighborhood.select_random_cell()
+        self.energy -= 1
+
+        self.feed()
+
+        if self.energy < 0:
+            self.remove()
+        elif self.random.random() < self.p_reproduce:
+            self.spawn_offspring()
+
+
+class Sheep(Animal):
+    """A sheep that walks around, reproduces (asexually) and gets eaten."""
+
+    def feed(self):
+        """If possible eat the food in the current location."""
+        # If there is grass available, eat it
+        if self.model.grass:
+            grass_patch = next(
+                obj for obj in self.cell.agents if isinstance(obj, GrassPatch)
+            )
+            if grass_patch.fully_grown:
+                self.energy += self.energy_from_food
+                grass_patch.fully_grown = False
+
+
+class Wolf(Animal):
+    """A wolf that walks around, reproduces (asexually) and eats sheep."""
+
+    def feed(self):
+        """If possible eat the food in the current location."""
+        sheep = [obj for obj in self.cell.agents if isinstance(obj, Sheep)]
+        if len(sheep) > 0:
+            sheep_to_eat = self.random.choice(sheep)
+            self.energy += self.energy_from_food
+
+            # Kill the sheep
+            sheep_to_eat.remove()
+
+
+class GrassPatch(FixedAgent):
+    """
+    A patch of grass that grows at a fixed rate and it is eaten by sheep
+    """
+
+    def __init__(self, model, fully_grown, countdown):
+        """
+        Creates a new patch of grass
+
+        Args:
+            grown: (boolean) Whether the patch of grass is fully grown or not
+            countdown: Time for the patch of grass to be fully grown again
+        """
+        super().__init__(model)
+        self.fully_grown = fully_grown
+        self.countdown = countdown
+
+    def step(self):
+        if not self.fully_grown:
+            if self.countdown <= 0:
+                # Set as fully grown
+                self.fully_grown = True
+                self.countdown = self.model.grass_regrowth_time
+            else:
+                self.countdown -= 1

mesa/examples/advanced/wolf_sheep/app.py

@@ -0,0 +1,84 @@
+from mesa.examples.advanced.wolf_sheep.agents import GrassPatch, Sheep, Wolf
+from mesa.examples.advanced.wolf_sheep.model import WolfSheep
+from mesa.visualization import (
+    Slider,
+    SolaraViz,
+    make_plot_component,
+    make_space_component,
+)
+
+
+def wolf_sheep_portrayal(agent):
+    if agent is None:
+        return
+
+    portrayal = {
+        "size": 25,
+    }
+
+    if isinstance(agent, Wolf):
+        portrayal["color"] = "tab:red"
+        portrayal["marker"] = "o"
+        portrayal["zorder"] = 2
+    elif isinstance(agent, Sheep):
+        portrayal["color"] = "tab:cyan"
+        portrayal["marker"] = "o"
+        portrayal["zorder"] = 2
+    elif isinstance(agent, GrassPatch):
+        if agent.fully_grown:
+            portrayal["color"] = "tab:green"
+        else:
+            portrayal["color"] = "tab:brown"
+        portrayal["marker"] = "s"
+        portrayal["size"] = 75
+
+    return portrayal
+
+
+model_params = {
+    # The following line is an example to showcase StaticText.
+    "grass": {
+        "type": "Select",
+        "value": True,
+        "values": [True, False],
+        "label": "grass regrowth enabled?",
+    },
+    "grass_regrowth_time": Slider("Grass Regrowth Time", 20, 1, 50),
+    "initial_sheep": Slider("Initial Sheep Population", 100, 10, 300),
+    "sheep_reproduce": Slider("Sheep Reproduction Rate", 0.04, 0.01, 1.0, 0.01),
+    "initial_wolves": Slider("Initial Wolf Population", 10, 5, 100),
+    "wolf_reproduce": Slider(
+        "Wolf Reproduction Rate",
+        0.05,
+        0.01,
+        1.0,
+        0.01,
+    ),
+    "wolf_gain_from_food": Slider("Wolf Gain From Food Rate", 20, 1, 50),
+    "sheep_gain_from_food": Slider("Sheep Gain From Food", 4, 1, 10),
+}
+
+
+def post_process(ax):
+    ax.set_aspect("equal")
+    ax.set_xticks([])
+    ax.set_yticks([])
+
+
+space_component = make_space_component(
+    wolf_sheep_portrayal, draw_grid=False, post_process=post_process
+)
+lineplot_component = make_plot_component(
+    {"Wolves": "tab:orange", "Sheep": "tab:cyan", "Grass": "tab:green"}
+)
+
+model = WolfSheep(grass=True)
+
+
+page = SolaraViz(
+    model,
+    components=[space_component, lineplot_component],
+    model_params=model_params,
+    name="Wolf Sheep",
+)
+page  # noqa

mesa/examples/advanced/wolf_sheep/model.py

@@ -0,0 +1,137 @@
+"""
+Wolf-Sheep Predation Model
+================================
+
+Replication of the model found in NetLogo:
+    Wilensky, U. (1997). NetLogo Wolf Sheep Predation model.
+    http://ccl.northwestern.edu/netlogo/models/WolfSheepPredation.
+    Center for Connected Learning and Computer-Based Modeling,
+    Northwestern University, Evanston, IL.
+"""
+
+import mesa
+from mesa.examples.advanced.wolf_sheep.agents import GrassPatch, Sheep, Wolf
+from mesa.experimental.cell_space import OrthogonalMooreGrid
+
+
+class WolfSheep(mesa.Model):
+    """
+    Wolf-Sheep Predation Model
+    """
+
+    height = 20
+    width = 20
+
+    initial_sheep = 100
+    initial_wolves = 50
+
+    sheep_reproduce = 0.04
+    wolf_reproduce = 0.05
+
+    wolf_gain_from_food = 20
+
+    grass = False
+    grass_regrowth_time = 30
+    sheep_gain_from_food = 4
+
+    description = (
+        "A model for simulating wolf and sheep (predator-prey) ecosystem modelling."
+    )
+
+    def __init__(
+        self,
+        width=20,
+        height=20,
+        initial_sheep=100,
+        initial_wolves=50,
+        sheep_reproduce=0.04,
+        wolf_reproduce=0.05,
+        wolf_gain_from_food=20,
+        grass=False,
+        grass_regrowth_time=30,
+        sheep_gain_from_food=4,
+        seed=None,
+    ):
+        """
+        Create a new Wolf-Sheep model with the given parameters.
+
+        Args:
+            initial_sheep: Number of sheep to start with
+            initial_wolves: Number of wolves to start with
+            sheep_reproduce: Probability of each sheep reproducing each step
+            wolf_reproduce: Probability of each wolf reproducing each step
+            wolf_gain_from_food: Energy a wolf gains from eating a sheep
+            grass: Whether to have the sheep eat grass for energy
+            grass_regrowth_time: How long it takes for a grass patch to regrow
+                                 once it is eaten
+            sheep_gain_from_food: Energy sheep gain from grass, if enabled.
+        """
+        super().__init__(seed=seed)
+        # Set parameters
+        self.width = width
+        self.height = height
+        self.initial_sheep = initial_sheep
+        self.initial_wolves = initial_wolves
+        self.grass = grass
+        self.grass_regrowth_time = grass_regrowth_time
+
+        self.grid = OrthogonalMooreGrid((self.width, self.height), torus=True)
+
+        collectors = {
+            "Wolves": lambda m: len(m.agents_by_type[Wolf]),
+            "Sheep": lambda m: len(m.agents_by_type[Sheep]),
+            "Grass": lambda m: len(
+                m.agents_by_type[GrassPatch].select(lambda a: a.fully_grown)
+            )
+            if m.grass
+            else -1,
+        }
+
+        self.datacollector = mesa.DataCollector(collectors)
+
+        # Create sheep:
+        for _ in range(self.initial_sheep):
+            x = self.random.randrange(self.width)
+            y = self.random.randrange(self.height)
+            energy = self.random.randrange(2 * self.sheep_gain_from_food)
+            Sheep(
+                self, energy, sheep_reproduce, sheep_gain_from_food, self.grid[(x, y)]
+            )
+
+        # Create wolves
+        for _ in range(self.initial_wolves):
+            x = self.random.randrange(self.width)
+            y = self.random.randrange(self.height)
+            energy = self.random.randrange(2 * self.wolf_gain_from_food)
+            Wolf(self, energy, wolf_reproduce, wolf_gain_from_food, self.grid[(x, y)])
+
+        # Create grass patches
+        if self.grass:
+            for cell in self.grid.all_cells:
+                fully_grown = self.random.choice([True, False])
+
+                if fully_grown:
+                    countdown = self.grass_regrowth_time
+                else:
+                    countdown = self.random.randrange(self.grass_regrowth_time)
+
+                patch = GrassPatch(self, fully_grown, countdown)
+                patch.cell = cell
+
+        self.running = True
+        self.datacollector.collect(self)
+
+    def step(self):
+        # This replicated the behavior of the old RandomActivationByType scheduler
+        # when using step(shuffle_types=True, shuffle_agents=True).
+        # Conceptually, it can be argued that this should be modelled differently.
+        self.random.shuffle(self.agent_types)
+        for agent_type in self.agent_types:
+            self.agents_by_type[agent_type].shuffle_do("step")
+
+        # collect data
+        self.datacollector.collect(self)
+
+    def run_model(self, step_count=200):
+        for _ in range(step_count):
+            self.step()