Mesa 3.0.0b0__py3-none-any.whl → 3.0.0b1__py3-none-any.whl

examples/advanced/sugarscape_g1mt/sugarscape_g1mt/trader_agents.py

@@ -0,0 +1,321 @@
+import math
+
+from mesa.experimental.cell_space import CellAgent
+
+from .resource_agents import Resource
+
+
+# Helper function
+def get_distance(cell_1, cell_2):
+    """
+    Calculate the Euclidean distance between two positions
+
+    used in trade.move()
+    """
+
+    x1, y1 = cell_1.coordinate
+    x2, y2 = cell_2.coordinate
+    dx = x1 - x2
+    dy = y1 - y2
+    return math.sqrt(dx**2 + dy**2)
+
+
+class Trader(CellAgent):
+    """
+    Trader:
+    - has a metabolism of sugar and spice
+    - harvest and trade sugar and spice to survive
+    """
+
+    def __init__(
+        self,
+        model,
+        cell,
+        sugar=0,
+        spice=0,
+        metabolism_sugar=0,
+        metabolism_spice=0,
+        vision=0,
+    ):
+        super().__init__(model)
+        self.cell = cell
+        self.sugar = sugar
+        self.spice = spice
+        self.metabolism_sugar = metabolism_sugar
+        self.metabolism_spice = metabolism_spice
+        self.vision = vision
+        self.prices = []
+        self.trade_partners = []
+
+    def get_resource(self, cell):
+        for agent in cell.agents:
+            if isinstance(agent, Resource):
+                return agent
+        raise Exception(f"Resource agent not found in the position {cell.coordinate}")
+
+    def get_trader(self, cell):
+        """
+        helper function used in self.trade_with_neighbors()
+        """
+
+        for agent in cell.agents:
+            if isinstance(agent, Trader):
+                return agent
+
+    def is_occupied_by_other(self, cell):
+        """
+        helper function part 1 of self.move()
+        """
+
+        if cell is self.cell:
+            # agent's position is considered unoccupied as agent can stay there
+            return False
+        # get contents of each cell in neighborhood
+        return any(isinstance(a, Trader) for a in cell.agents)
+
+    def calculate_welfare(self, sugar, spice):
+        """
+        helper function
+
+        part 2 self.move()
+        self.trade()
+        """
+
+        # calculate total resources
+        m_total = self.metabolism_sugar + self.metabolism_spice
+        # Cobb-Douglas functional form; starting on p. 97
+        # on Growing Artificial Societies
+        return sugar ** (self.metabolism_sugar / m_total) * spice ** (
+            self.metabolism_spice / m_total
+        )
+
+    def is_starved(self):
+        """
+        Helper function for self.maybe_die()
+        """
+
+        return (self.sugar <= 0) or (self.spice <= 0)
+
+    def calculate_MRS(self, sugar, spice):
+        """
+        Helper function for
+          - self.trade()
+          - self.maybe_self_spice()
+
+        Determines what trader agent needs and can give up
+        """
+
+        return (spice / self.metabolism_spice) / (sugar / self.metabolism_sugar)
+
+    def calculate_sell_spice_amount(self, price):
+        """
+        helper function for self.maybe_sell_spice() which is called from
+        self.trade()
+        """
+
+        if price >= 1:
+            sugar = 1
+            spice = int(price)
+        else:
+            sugar = int(1 / price)
+            spice = 1
+        return sugar, spice
+
+    def sell_spice(self, other, sugar, spice):
+        """
+        used in self.maybe_sell_spice()
+
+        exchanges sugar and spice between traders
+        """
+
+        self.sugar += sugar
+        other.sugar -= sugar
+        self.spice -= spice
+        other.spice += spice
+
+    def maybe_sell_spice(self, other, price, welfare_self, welfare_other):
+        """
+        helper function for self.trade()
+        """
+
+        sugar_exchanged, spice_exchanged = self.calculate_sell_spice_amount(price)
+
+        # Assess new sugar and spice amount - what if change did occur
+        self_sugar = self.sugar + sugar_exchanged
+        other_sugar = other.sugar - sugar_exchanged
+        self_spice = self.spice - spice_exchanged
+        other_spice = other.spice + spice_exchanged
+
+        # double check to ensure agents have resources
+
+        if (
+            (self_sugar <= 0)
+            or (other_sugar <= 0)
+            or (self_spice <= 0)
+            or (other_spice <= 0)
+        ):
+            return False
+
+        # trade criteria #1 - are both agents better off?
+        both_agents_better_off = (
+            welfare_self < self.calculate_welfare(self_sugar, self_spice)
+        ) and (welfare_other < other.calculate_welfare(other_sugar, other_spice))
+
+        # trade criteria #2 is their mrs crossing with potential trade
+        mrs_not_crossing = self.calculate_MRS(
+            self_sugar, self_spice
+        ) > other.calculate_MRS(other_sugar, other_spice)
+
+        if not (both_agents_better_off and mrs_not_crossing):
+            return False
+
+        # criteria met, execute trade
+        self.sell_spice(other, sugar_exchanged, spice_exchanged)
+
+        return True
+
+    def trade(self, other):
+        """
+        helper function used in trade_with_neighbors()
+
+        other is a trader agent object
+        """
+
+        # sanity check to verify code is working as expected
+        assert self.sugar > 0
+        assert self.spice > 0
+        assert other.sugar > 0
+        assert other.spice > 0
+
+        # calculate marginal rate of substitution in Growing Artificial Societies p. 101
+        mrs_self = self.calculate_MRS(self.sugar, self.spice)
+        mrs_other = other.calculate_MRS(other.sugar, other.spice)
+
+        # calculate each agents welfare
+        welfare_self = self.calculate_welfare(self.sugar, self.spice)
+        welfare_other = other.calculate_welfare(other.sugar, other.spice)
+
+        if math.isclose(mrs_self, mrs_other):
+            return
+
+        # calculate price
+        price = math.sqrt(mrs_self * mrs_other)
+
+        if mrs_self > mrs_other:
+            # self is a sugar buyer, spice seller
+            sold = self.maybe_sell_spice(other, price, welfare_self, welfare_other)
+            # no trade - criteria not met
+            if not sold:
+                return
+        else:
+            # self is a spice buyer, sugar seller
+            sold = other.maybe_sell_spice(self, price, welfare_other, welfare_self)
+            # no trade - criteria not met
+            if not sold:
+                return
+
+        # Capture data
+        self.prices.append(price)
+        self.trade_partners.append(other.unique_id)
+
+        # continue trading
+        self.trade(other)
+
+    ######################################################################
+    #                                                                    #
+    #                      MAIN TRADE FUNCTIONS                          #
+    #                                                                    #
+    ######################################################################
+
+    def move(self):
+        """
+        Function for trader agent to identify optimal move for each step in 4 parts
+        1 - identify all possible moves
+        2 - determine which move maximizes welfare
+        3 - find closest best option
+        4 - move
+        """
+
+        # 1. identify all possible moves
+
+        neighboring_cells = [
+            cell
+            for cell in self.cell.get_neighborhood(self.vision, include_center=True)
+            if not self.is_occupied_by_other(cell)
+        ]
+
+        # 2. determine which move maximizes welfare
+
+        welfares = [
+            self.calculate_welfare(
+                self.sugar + self.get_resource(cell).sugar_amount,
+                self.spice + self.get_resource(cell).spice_amount,
+            )
+            for cell in neighboring_cells
+        ]
+
+        # 3. Find closest best option
+
+        # find the highest welfare in welfares
+        max_welfare = max(welfares)
+        # get the index of max welfare cells
+        candidate_indices = [
+            i for i in range(len(welfares)) if math.isclose(welfares[i], max_welfare)
+        ]
+
+        # convert index to positions of those cells
+        candidates = [neighboring_cells[i] for i in candidate_indices]
+
+        min_dist = min(get_distance(self.cell, cell) for cell in candidates)
+
+        final_candidates = [
+            cell
+            for cell in candidates
+            if math.isclose(get_distance(self.cell, cell), min_dist, rel_tol=1e-02)
+        ]
+        # 4. Move Agent
+        self.cell = self.random.choice(final_candidates)
+
+    def eat(self):
+        patch = self.get_resource(self.cell)
+        if patch.sugar_amount > 0:
+            self.sugar += patch.sugar_amount
+            patch.sugar_amount = 0
+        self.sugar -= self.metabolism_sugar
+
+        if patch.spice_amount > 0:
+            self.spice += patch.spice_amount
+            patch.spice_amount = 0
+        self.spice -= self.metabolism_spice
+
+    def maybe_die(self):
+        """
+        Function to remove Traders who have consumed all their sugar or spice
+        """
+
+        if self.is_starved():
+            self.remove()
+
+    def trade_with_neighbors(self):
+        """
+        Function for trader agents to decide who to trade with in three parts
+
+        1- identify neighbors who can trade
+        2- trade (2 sessions)
+        3- collect data
+        """
+
+        neighbor_agents = [
+            self.get_trader(cell)
+            for cell in self.cell.get_neighborhood(radius=self.vision)
+            if self.is_occupied_by_other(cell)
+        ]
+
+        if len(neighbor_agents) == 0:
+            return
+
+            # iterate through traders in neighboring cells and trade
+        for a in neighbor_agents:
+            self.trade(a)
+
+        return

examples/advanced/sugarscape_g1mt/tests.py

@@ -0,0 +1,72 @@
+import random
+
+import numpy as np
+from scipy import stats
+from sugarscape_g1mt.model import SugarscapeG1mt, flatten
+from sugarscape_g1mt.trader_agents import Trader
+
+random.seed(1)
+
+
+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()
+    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

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.

examples/advanced/wolf_sheep/requirements.txt

@@ -0,0 +1 @@
+mesa~=2.0

examples/advanced/wolf_sheep/run.py

@@ -0,0 +1,3 @@
+from wolf_sheep.server import server
+
+server.launch(open_browser=True)

examples/advanced/wolf_sheep/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

examples/advanced/wolf_sheep/wolf_sheep/model.py

@@ -0,0 +1,136 @@
+"""
+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.experimental.cell_space import OrthogonalMooreGrid
+
+from .agents import GrassPatch, Sheep, Wolf
+
+
+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=None)
+        # 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]),
+        }
+
+        if grass:
+            collectors["Grass"] = lambda m: len(m.agents_by_type[GrassPatch])
+
+        self.datacollector = mesa.DataCollector(collectors)
+
+        # Create sheep:
+        for i 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 i in range(step_count):
+            self.step()