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

mesa/examples/advanced/pd_grid/app.py

@@ -0,0 +1,54 @@
+"""
+Solara-based visualization for the Spatial Prisoner's Dilemma Model.
+"""
+
+from mesa.examples.advanced.pd_grid.model import PdGrid
+from mesa.visualization import (
+    Slider,
+    SolaraViz,
+    make_plot_component,
+    make_space_component,
+)
+
+
+def pd_agent_portrayal(agent):
+    """
+    Portrayal function for rendering PD agents in the visualization.
+    """
+    return {
+        "color": "blue" if agent.move == "C" else "red",
+        "marker": "s",  # square marker
+        "size": 25,
+    }
+
+
+# Model parameters
+model_params = {
+    "width": Slider("Grid Width", value=50, min=10, max=100, step=1),
+    "height": Slider("Grid Height", value=50, min=10, max=100, step=1),
+    "activation_order": {
+        "type": "Select",
+        "value": "Random",
+        "values": PdGrid.activation_regimes,
+        "label": "Activation Regime",
+    },
+}
+
+
+# Create grid visualization component using Altair
+grid_viz = make_space_component(agent_portrayal=pd_agent_portrayal)
+
+# Create plot for tracking cooperating agents over time
+plot_component = make_plot_component("Cooperating_Agents")
+
+# Initialize model
+initial_model = PdGrid()
+
+# Create visualization with all components
+page = SolaraViz(
+    model=initial_model,
+    components=[grid_viz, plot_component],
+    model_params=model_params,
+    name="Spatial Prisoner's Dilemma",
+)
+page  # noqa B018

mesa/examples/advanced/pd_grid/model.py

@@ -0,0 +1,71 @@
+import mesa
+from mesa.examples.advanced.pd_grid.agents import PDAgent
+from mesa.experimental.cell_space import OrthogonalMooreGrid
+
+
+class PdGrid(mesa.Model):
+    """Model class for iterated, spatial prisoner's dilemma model."""
+
+    activation_regimes = ["Sequential", "Random", "Simultaneous"]
+
+    # This dictionary holds the payoff for this agent,
+    # keyed on: (my_move, other_move)
+
+    payoff = {("C", "C"): 1, ("C", "D"): 0, ("D", "C"): 1.6, ("D", "D"): 0}
+
+    def __init__(
+        self, width=50, height=50, activation_order="Random", payoffs=None, seed=None
+    ):
+        """
+        Create a new Spatial Prisoners' Dilemma Model.
+
+        Args:
+            width, height: Grid size. There will be one agent per grid cell.
+            activation_order: Can be "Sequential", "Random", or "Simultaneous".
+                           Determines the agent activation regime.
+            payoffs: (optional) Dictionary of (move, neighbor_move) payoffs.
+        """
+        super().__init__(seed=seed)
+        self.activation_order = activation_order
+        self.grid = OrthogonalMooreGrid((width, height), torus=True)
+
+        if payoffs is not None:
+            self.payoff = payoffs
+
+        # Create agents
+        for x in range(width):
+            for y in range(height):
+                agent = PDAgent(self)
+                agent.cell = self.grid[(x, y)]
+
+        self.datacollector = mesa.DataCollector(
+            {
+                "Cooperating_Agents": lambda m: len(
+                    [a for a in m.agents if a.move == "C"]
+                )
+            }
+        )
+
+        self.running = True
+        self.datacollector.collect(self)
+
+    def step(self):
+        # Activate all agents, based on the activation regime
+        match self.activation_order:
+            case "Sequential":
+                self.agents.do("step")
+            case "Random":
+                self.agents.shuffle_do("step")
+            case "Simultaneous":
+                self.agents.do("step")
+                self.agents.do("advance")
+            case _:
+                raise ValueError(f"Unknown activation order: {self.activation_order}")
+
+        # Collect data
+        self.datacollector.collect(self)
+
+    def run(self, n):
+        """Run the model for n steps."""
+        for _ in range(n):
+            self.step()

mesa/examples/advanced/sugarscape_g1mt/Readme.md

@@ -0,0 +1,64 @@
+# Sugarscape Constant Growback Model with Traders
+
+## Summary
+
+This is Epstein & Axtell's Sugarscape model with Traders, a detailed description is in Chapter four of
+*Growing Artificial Societies: Social Science from the Bottom Up (1996)*. The model shows an emergent price equilibrium can happen via a decentralized dynamics.
+
+This code generally matches the code in the Complexity Explorer Tutorial, but in `.py` instead of `.ipynb` format.
+
+### Agents:
+
+- **Resource**:  Resource agents grow back at one unit of sugar and spice per time step up to a specified max amount and can be harvested and traded by the trader agents.
+  (if you do the interactive run, the color will be green if the resource agent has a bigger amount of sugar, or yellow if it has a bigger amount of spice)
+- **Traders**: Trader agents have the following attributes: (1) metabolism for sugar, (2) metabolism for spice, (3) vision,
+  (4) initial sugar endowment and (5) initial spice endowment. The traverse the landscape harvesting sugar and spice and
+trading with other agents. If they run out of sugar or spice then they are removed from the model. (red circle if you do the interactive run)
+
+The trader agents traverse the landscape according to rule **M**:
+- Look out as far as vision permits in the four principal lattice directions and identify the unoccupied site(s).
+- Considering only unoccupied sites find the nearest position that produces the most welfare using the Cobb-Douglas function.
+- Move to the new position
+- Collect all the resources (sugar and spice) at that location
+(Epstein and Axtell, 1996, p. 99)
+
+The traders trade according to rule **T**:
+- Agents and potential trade partner compute their marginal rates of substitution (MRS), if they are equal *end*.
+- Exchange resources, with spice flowing from the agent with the higher MRS to the agent with the lower MRS and sugar
+flowing the opposite direction.
+- The price (p) is calculated by taking the geometric mean of the agents' MRS.
+- If p > 1 then p units of spice are traded for 1 unit of sugar; if p < 1 then 1/p units of sugar for 1 unit of spice
+- The trade occurs if it will (a) make both agent better off (increases MRS) and (b) does not cause the agents' MRS to
+cross over one another otherwise *end*.
+- This process then repeats until an *end* condition is met.
+(Epstein and Axtell, 1996, p. 105)
+
+The model demonstrates several Mesa concepts and features:
+ - OrthogonalMooreGrid
+ - Multiple agent types (traders, sugar, spice)
+ - Dynamically removing agents from the grid and schedule when they die
+ - Data Collection at the model and agent level
+ - custom solara matplotlib space visualization
+
+
+## How to Run
+To run the model interactively:
+
+```
+  $ solara run app.py
+```
+
+Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press Reset, then Run.
+
+## Files
+
+* `model.py`: The Sugarscape Constant Growback with Traders model.
+* `agents.py`: Defines the Trader agent class and the Resource agent class which contains an amount of sugar and spice.
+* `app.py`: Runs a visualization server via Solara (`solara run app.py`).
+* `sugar_map.txt`: Provides sugar and spice landscape in raster type format.
+* `tests.py`: Has tests to ensure that the model reproduces the results in shown in Growing Artificial Societies.
+
+## Additional Resources
+
+- [Growing Artificial Societies](https://mitpress.mit.edu/9780262550253/growing-artificial-societies/)
+- [Complexity Explorer Sugarscape with Traders Tutorial](https://www.complexityexplorer.org/courses/172-agent-based-models-with-python-an-introduction-to-mesa)

mesa/examples/advanced/sugarscape_g1mt/agents.py

@@ -0,0 +1,344 @@
+import math
+
+from mesa.experimental.cell_space import CellAgent, FixedAgent
+
+
+# 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 Resource(FixedAgent):
+    """
+    Resource:
+    - contains an amount of sugar and spice
+    - grows 1 amount of sugar at each turn
+    - grows 1 amount of spice at each turn
+    """
+
+    def __init__(self, model, max_sugar, max_spice, cell):
+        super().__init__(model)
+        self.sugar_amount = max_sugar
+        self.max_sugar = max_sugar
+        self.spice_amount = max_spice
+        self.max_spice = max_spice
+        self.cell = cell
+
+    def step(self):
+        """
+        Growth function, adds one unit of sugar and spice each step up to
+        max amount
+        """
+        self.sugar_amount = min([self.max_sugar, self.sugar_amount + 1])
+        self.spice_amount = min([self.max_spice, self.spice_amount + 1])
+
+
+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

mesa/examples/advanced/sugarscape_g1mt/app.py

@@ -0,0 +1,62 @@
+import numpy as np
+import solara
+from matplotlib.figure import Figure
+
+from mesa.examples.advanced.sugarscape_g1mt.agents import Trader
+from mesa.examples.advanced.sugarscape_g1mt.model import SugarscapeG1mt
+from mesa.visualization import SolaraViz, make_plot_component
+
+
+def SpaceDrawer(model):
+    def portray(g):
+        layers = {
+            "sugar": [[np.nan for j in range(g.height)] for i in range(g.width)],
+            "spice": [[np.nan for j in range(g.height)] for i in range(g.width)],
+            "trader": {"x": [], "y": [], "c": "tab:red", "marker": "o", "s": 10},
+        }
+
+        for agent in g.all_cells.agents:
+            i, j = agent.cell.coordinate
+            if isinstance(agent, Trader):
+                layers["trader"]["x"].append(i)
+                layers["trader"]["y"].append(j)
+            else:
+                # Don't visualize resource with value <= 1.
+                layers["sugar"][i][j] = (
+                    agent.sugar_amount if agent.sugar_amount > 1 else np.nan
+                )
+                layers["spice"][i][j] = (
+                    agent.spice_amount if agent.spice_amount > 1 else np.nan
+                )
+        return layers
+
+    fig = Figure()
+    ax = fig.subplots()
+    out = portray(model.grid)
+    # Sugar
+    # Important note: imshow by default draws from upper left. You have to
+    # always explicitly specify origin="lower".
+    im = ax.imshow(out["sugar"], cmap="spring", origin="lower")
+    fig.colorbar(im, orientation="vertical")
+    # Spice
+    ax.imshow(out["spice"], cmap="winter", origin="lower")
+    # Trader
+    ax.scatter(**out["trader"])
+    ax.set_axis_off()
+    return solara.FigureMatplotlib(fig)
+
+
+model_params = {
+    "width": 50,
+    "height": 50,
+}
+
+model1 = SugarscapeG1mt(50, 50)
+
+page = SolaraViz(
+    model1,
+    components=[SpaceDrawer, make_plot_component(["Trader", "Price"])],
+    name="Sugarscape {G1, M, T}",
+    play_interval=150,
+)
+page  # noqa