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

examples/advanced/wolf_sheep/wolf_sheep/server.py

@@ -0,0 +1,78 @@
+import mesa
+from wolf_sheep.agents import GrassPatch, Sheep, Wolf
+from wolf_sheep.model import WolfSheep
+
+
+def wolf_sheep_portrayal(agent):
+    if agent is None:
+        return
+
+    portrayal = {}
+
+    if type(agent) is Sheep:
+        portrayal["Shape"] = "wolf_sheep/resources/sheep.png"
+        # https://icons8.com/web-app/433/sheep
+        portrayal["scale"] = 0.9
+        portrayal["Layer"] = 1
+
+    elif type(agent) is Wolf:
+        portrayal["Shape"] = "wolf_sheep/resources/wolf.png"
+        # https://icons8.com/web-app/36821/German-Shepherd
+        portrayal["scale"] = 0.9
+        portrayal["Layer"] = 2
+        portrayal["text"] = round(agent.energy, 1)
+        portrayal["text_color"] = "White"
+
+    elif type(agent) is GrassPatch:
+        if agent.fully_grown:
+            portrayal["Color"] = ["#00FF00", "#00CC00", "#009900"]
+        else:
+            portrayal["Color"] = ["#84e184", "#adebad", "#d6f5d6"]
+        portrayal["Shape"] = "rect"
+        portrayal["Filled"] = "true"
+        portrayal["Layer"] = 0
+        portrayal["w"] = 1
+        portrayal["h"] = 1
+
+    return portrayal
+
+
+canvas_element = mesa.visualization.CanvasGrid(wolf_sheep_portrayal, 20, 20, 500, 500)
+chart_element = mesa.visualization.ChartModule(
+    [
+        {"Label": "Wolves", "Color": "#AA0000"},
+        {"Label": "Sheep", "Color": "#666666"},
+        {"Label": "Grass", "Color": "#00AA00"},
+    ]
+)
+
+model_params = {
+    # The following line is an example to showcase StaticText.
+    "title": mesa.visualization.StaticText("Parameters:"),
+    "grass": mesa.visualization.Checkbox("Grass Enabled", True),
+    "grass_regrowth_time": mesa.visualization.Slider("Grass Regrowth Time", 20, 1, 50),
+    "initial_sheep": mesa.visualization.Slider(
+        "Initial Sheep Population", 100, 10, 300
+    ),
+    "sheep_reproduce": mesa.visualization.Slider(
+        "Sheep Reproduction Rate", 0.04, 0.01, 1.0, 0.01
+    ),
+    "initial_wolves": mesa.visualization.Slider("Initial Wolf Population", 50, 10, 300),
+    "wolf_reproduce": mesa.visualization.Slider(
+        "Wolf Reproduction Rate",
+        0.05,
+        0.01,
+        1.0,
+        0.01,
+        description="The rate at which wolf agents reproduce.",
+    ),
+    "wolf_gain_from_food": mesa.visualization.Slider(
+        "Wolf Gain From Food Rate", 20, 1, 50
+    ),
+    "sheep_gain_from_food": mesa.visualization.Slider("Sheep Gain From Food", 4, 1, 10),
+}
+
+server = mesa.visualization.ModularServer(
+    WolfSheep, [canvas_element, chart_element], "Wolf Sheep Predation", model_params
+)
+server.port = 8521

examples/basic/__init__.py

@@ -0,0 +1,13 @@
+from .boid_flockers.model import BoidFlockers
+from .boltzmann_wealth_model.model import BoltzmannWealthModel
+from .conways_game_of_life.model import ConwaysGameOfLife
+from .schelling.model import Schelling
+from .virus_on_network.model import VirusOnNetwork
+
+__all__ = [
+    "BoidFlockers",
+    "BoltzmannWealthModel",
+    "ConwaysGameOfLife",
+    "Schelling",
+    "VirusOnNetwork",
+]

examples/basic/boid_flockers/Readme.md

@@ -0,0 +1,43 @@
+# Boids Flockers
+
+## Summary
+
+An implementation of Craig Reynolds's Boids flocker model. Agents (simulated birds) try to fly towards the average position of their neighbors and in the same direction as them, while maintaining a minimum distance. This produces flocking behavior.
+
+This model tests Mesa's continuous space feature, and uses numpy arrays to represent vectors. It also demonstrates how to create custom visualization components.
+
+## Installation
+
+To install the dependencies use pip and the requirements.txt in this directory. e.g.
+
+```
+    $ pip install -r requirements.txt
+```
+
+## How to Run
+
+* To launch the visualization interactively, run ``mesa runserver`` in this directory. e.g.
+
+```
+$ mesa runserver
+```
+
+or
+
+Directly run the file ``run.py`` in the terminal. e.g.
+
+```
+    $ python run.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](model.py): Core model file; contains the Boid Model and Boid Agent class.
+* [app.py](app.py): Visualization code.
+
+## Further Reading
+
+The following link can be visited for more information on the boid flockers model:
+https://cs.stanford.edu/people/eroberts/courses/soco/projects/2008-09/modeling-natural-systems/boids.html

examples/basic/boid_flockers/agents.py

@@ -0,0 +1,71 @@
+import numpy as np
+
+from mesa import Agent
+
+
+class Boid(Agent):
+    """A Boid-style flocker agent.
+
+    The agent follows three behaviors to flock:
+        - Cohesion: steering towards neighboring agents.
+        - Separation: avoiding getting too close to any other agent.
+        - Alignment: try to fly in the same direction as the neighbors.
+
+    Boids have a vision that defines the radius in which they look for their
+    neighbors to flock with. Their speed (a scalar) and direction (a vector)
+    define their movement. Separation is their desired minimum distance from
+    any other Boid.
+    """
+
+    def __init__(
+        self,
+        model,
+        speed,
+        direction,
+        vision,
+        separation,
+        cohere=0.03,
+        separate=0.015,
+        match=0.05,
+    ):
+        """Create a new Boid flocker agent.
+
+        Args:
+            speed: Distance to move per step.
+            direction: numpy vector for the Boid's direction of movement.
+            vision: Radius to look around for nearby Boids.
+            separation: Minimum distance to maintain from other Boids.
+            cohere: the relative importance of matching neighbors' positions
+            separate: the relative importance of avoiding close neighbors
+            match: the relative importance of matching neighbors' headings
+        """
+        super().__init__(model)
+        self.speed = speed
+        self.direction = direction
+        self.vision = vision
+        self.separation = separation
+        self.cohere_factor = cohere
+        self.separate_factor = separate
+        self.match_factor = match
+        self.neighbors = None
+
+    def step(self):
+        """Get the Boid's neighbors, compute the new vector, and move accordingly."""
+        self.neighbors = self.model.space.get_neighbors(self.pos, self.vision, False)
+        n = 0
+        match_vector, separation_vector, cohere = np.zeros((3, 2))
+        for neighbor in self.neighbors:
+            n += 1
+            heading = self.model.space.get_heading(self.pos, neighbor.pos)
+            cohere += heading
+            if self.model.space.get_distance(self.pos, neighbor.pos) < self.separation:
+                separation_vector -= heading
+            match_vector += neighbor.direction
+        n = max(n, 1)
+        cohere = cohere * self.cohere_factor
+        separation_vector = separation_vector * self.separate_factor
+        match_vector = match_vector * self.match_factor
+        self.direction += (cohere + separation_vector + match_vector) / n
+        self.direction /= np.linalg.norm(self.direction)
+        new_pos = self.pos + self.direction * self.speed
+        self.model.space.move_agent(self, new_pos)

examples/basic/boid_flockers/app.py

@@ -0,0 +1,59 @@
+from mesa.visualization import Slider, SolaraViz, make_space_matplotlib
+
+from .model import BoidFlockers
+
+
+def boid_draw(agent):
+    if not agent.neighbors:  # Only for the first Frame
+        neighbors = len(agent.model.space.get_neighbors(agent.pos, agent.vision, False))
+    else:
+        neighbors = len(agent.neighbors)
+
+    if neighbors <= 1:
+        return {"color": "red", "size": 20}
+    elif neighbors >= 2:
+        return {"color": "green", "size": 20}
+
+
+model_params = {
+    "population": Slider(
+        label="Number of boids",
+        value=100,
+        min=10,
+        max=200,
+        step=10,
+    ),
+    "width": 100,
+    "height": 100,
+    "speed": Slider(
+        label="Speed of Boids",
+        value=5,
+        min=1,
+        max=20,
+        step=1,
+    ),
+    "vision": Slider(
+        label="Vision of Bird (radius)",
+        value=10,
+        min=1,
+        max=50,
+        step=1,
+    ),
+    "separation": Slider(
+        label="Minimum Separation",
+        value=2,
+        min=1,
+        max=20,
+        step=1,
+    ),
+}
+
+model = BoidFlockers()
+
+page = SolaraViz(
+    model,
+    [make_space_matplotlib(agent_portrayal=boid_draw)],
+    model_params=model_params,
+    name="Boid Flocking Model",
+)
+page  # noqa

examples/basic/boid_flockers/model.py

@@ -0,0 +1,70 @@
+"""Flockers.
+=============================================================
+A Mesa implementation of Craig Reynolds's Boids flocker model.
+Uses numpy arrays to represent vectors.
+"""
+
+import numpy as np
+
+import mesa
+
+from .agents import Boid
+
+
+class BoidFlockers(mesa.Model):
+    """Flocker model class. Handles agent creation, placement and scheduling."""
+
+    def __init__(
+        self,
+        seed=None,
+        population=100,
+        width=100,
+        height=100,
+        vision=10,
+        speed=1,
+        separation=1,
+        cohere=0.03,
+        separate=0.015,
+        match=0.05,
+    ):
+        """Create a new Flockers model.
+
+        Args:
+            population: Number of Boids
+            width, height: Size of the space.
+            speed: How fast should the Boids move.
+            vision: How far around should each Boid look for its neighbors
+            separation: What's the minimum distance each Boid will attempt to
+                    keep from any other
+            cohere, separate, match: factors for the relative importance of
+                    the three drives.
+        """
+        super().__init__(seed=seed)
+        self.population = population
+        self.vision = vision
+        self.speed = speed
+        self.separation = separation
+
+        self.space = mesa.space.ContinuousSpace(width, height, True)
+        self.factors = {"cohere": cohere, "separate": separate, "match": match}
+        self.make_agents()
+
+    def make_agents(self):
+        """Create self.population agents, with random positions and starting headings."""
+        for _ in range(self.population):
+            x = self.random.random() * self.space.x_max
+            y = self.random.random() * self.space.y_max
+            pos = np.array((x, y))
+            direction = np.random.random(2) * 2 - 1
+            boid = Boid(
+                model=self,
+                speed=self.speed,
+                direction=direction,
+                vision=self.vision,
+                separation=self.separation,
+                **self.factors,
+            )
+            self.space.place_agent(boid, pos)
+
+    def step(self):
+        self.agents.shuffle_do("step")

examples/basic/boltzmann_wealth_model/Readme.md

@@ -0,0 +1,60 @@
+# Boltzmann Wealth Model (Tutorial)
+
+## Summary
+
+A simple model of agents exchanging wealth. All agents start with the same amount of money. Every step, each agent with one unit of money or more gives one unit of wealth to another random agent. This is the model described in the [Intro Tutorial](https://mesa.readthedocs.io/en/latest/tutorials/intro_tutorial.html), with the completed code.
+
+If you want to go over the step-by-step tutorial, please go and run the [Jupyter Notebook](https://github.com/projectmesa/mesa/blob/main/docs/tutorials/intro_tutorial.ipynb). The code here runs the finalized code in the last cells directly.
+
+As the model runs, the distribution of wealth among agents goes from being perfectly uniform (all agents have the same starting wealth), to highly skewed -- a small number have high wealth, more have none at all.
+
+## How to Run
+
+To follow the tutorial example, launch the Jupyter Notebook and run the code in ``Introduction to Mesa Tutorial Code.ipynb`` which you can find in the main mesa repo [here](https://github.com/projectmesa/mesa/blob/main/docs/tutorials/intro_tutorial.ipynb)
+
+Make sure to install the requirements first:
+
+```
+    $ pip install -r requirements.txt
+```
+
+To launch the interactive server, as described in the [last section of the tutorial](https://mesa.readthedocs.io/en/latest/tutorials/intro_tutorial.html#adding-visualization), run:
+
+```
+    $ solara run app.py
+```
+
+If your browser doesn't open automatically, point it to [http://127.0.0.1:8765/](http://127.0.0.1:8765/). When the visualization loads, click on the Play button.
+
+
+## Files
+
+* ``model.py``: Final version of the model.
+* ``app.py``: Code for the interactive visualization.
+
+## Optional
+
+An optional visualization is also provided using Streamlit, which is another popular Python library for creating interactive web applications.
+
+To run the Streamlit app, you will need to install the `streamlit` and `altair` libraries:
+
+```
+    $ pip install streamlit altair
+```
+
+Then, you can run the Streamlit app using the following command:
+
+```
+    $ streamlit run st_app.py
+```
+
+## Further Reading
+
+The full tutorial describing how the model is built can be found at:
+https://mesa.readthedocs.io/en/latest/tutorials/intro_tutorial.html
+
+This model is drawn from econophysics and presents a statistical mechanics approach to wealth distribution. Some examples of further reading on the topic can be found at:
+
+[Milakovic, M. A Statistical Equilibrium Model of Wealth Distribution. February, 2001.](https://editorialexpress.com/cgi-bin/conference/download.cgi?db_name=SCE2001&paper_id=214)
+
+[Dragulescu, A and Yakovenko, V. Statistical Mechanics of Money, Income, and Wealth: A Short Survey. November, 2002](http://arxiv.org/pdf/cond-mat/0211175v1.pdf)

examples/basic/boltzmann_wealth_model/agents.py

@@ -0,0 +1,31 @@
+from mesa import Agent
+
+
+class MoneyAgent(Agent):
+    """An agent with fixed initial wealth."""
+
+    def __init__(self, model):
+        super().__init__(model)
+        self.wealth = 1
+
+    def move(self):
+        possible_steps = self.model.grid.get_neighborhood(
+            self.pos, moore=True, include_center=False
+        )
+        new_position = self.random.choice(possible_steps)
+        self.model.grid.move_agent(self, new_position)
+
+    def give_money(self):
+        cellmates = self.model.grid.get_cell_list_contents([self.pos])
+        cellmates.pop(
+            cellmates.index(self)
+        )  # Ensure agent is not giving money to itself
+        if len(cellmates) > 0:
+            other = self.random.choice(cellmates)
+            other.wealth += 1
+            self.wealth -= 1
+
+    def step(self):
+        self.move()
+        if self.wealth > 0:
+            self.give_money()

examples/basic/boltzmann_wealth_model/app.py

@@ -0,0 +1,66 @@
+from mesa.visualization import (
+    SolaraViz,
+    make_plot_measure,
+    make_space_matplotlib,
+)
+
+from .model import BoltzmannWealthModel
+
+
+def agent_portrayal(agent):
+    size = 10
+    color = "tab:red"
+    if agent.wealth > 0:
+        size = 50
+        color = "tab:blue"
+    return {"size": size, "color": color}
+
+
+model_params = {
+    "n": {
+        "type": "SliderInt",
+        "value": 50,
+        "label": "Number of agents:",
+        "min": 10,
+        "max": 100,
+        "step": 1,
+    },
+    "width": 10,
+    "height": 10,
+}
+
+# Create initial model instance
+model1 = BoltzmannWealthModel(50, 10, 10)
+
+# Create visualization elements. The visualization elements are solara components
+# that receive the model instance as a "prop" and display it in a certain way.
+# Under the hood these are just classes that receive the model instance.
+# You can also author your own visualization elements, which can also be functions
+# that receive the model instance and return a valid solara component.
+SpaceGraph = make_space_matplotlib(agent_portrayal)
+GiniPlot = make_plot_measure("Gini")
+
+# Create the SolaraViz page. This will automatically create a server and display the
+# visualization elements in a web browser.
+# Display it using the following command in the example directory:
+# solara run app.py
+# It will automatically update and display any changes made to this file
+page = SolaraViz(
+    model1,
+    components=[SpaceGraph, GiniPlot],
+    model_params=model_params,
+    name="Boltzmann Wealth Model",
+)
+page  # noqa
+
+
+# In a notebook environment, we can also display the visualization elements directly
+# SpaceGraph(model1)
+# GiniPlot(model1)
+
+# The plots will be static. If you want to pick up model steps,
+# you have to make the model reactive first
+# reactive_model = solara.reactive(model1)
+# SpaceGraph(reactive_model)
+# In a different notebook block:
+# reactive_model.value.step()

examples/basic/boltzmann_wealth_model/model.py

@@ -0,0 +1,44 @@
+import mesa
+
+from .agents import MoneyAgent
+
+
+class BoltzmannWealthModel(mesa.Model):
+    """A simple model of an economy where agents exchange currency at random.
+
+    All the agents begin with one unit of currency, and each time step can give
+    a unit of currency to another agent. Note how, over time, this produces a
+    highly skewed distribution of wealth.
+    """
+
+    def __init__(self, n=100, width=10, height=10):
+        super().__init__()
+        self.num_agents = n
+        self.grid = mesa.space.MultiGrid(width, height, True)
+
+        self.datacollector = mesa.DataCollector(
+            model_reporters={"Gini": self.compute_gini},
+            agent_reporters={"Wealth": "wealth"},
+        )
+        # Create agents
+        for _ in range(self.num_agents):
+            a = MoneyAgent(self)
+
+            # Add the agent to a random grid cell
+            x = self.random.randrange(self.grid.width)
+            y = self.random.randrange(self.grid.height)
+            self.grid.place_agent(a, (x, y))
+
+        self.running = True
+        self.datacollector.collect(self)
+
+    def step(self):
+        self.agents.shuffle_do("step")
+        self.datacollector.collect(self)
+
+    def compute_gini(self):
+        agent_wealths = [agent.wealth for agent in self.agents]
+        x = sorted(agent_wealths)
+        n = self.num_agents
+        b = sum(xi * (n - i) for i, xi in enumerate(x)) / (n * sum(x))
+        return 1 + (1 / n) - 2 * b

examples/basic/boltzmann_wealth_model/st_app.py

@@ -0,0 +1,115 @@
+# Run with streamlit run st_app.py
+
+import time
+
+import altair as alt
+import pandas as pd
+import streamlit as st
+from model import BoltzmannWealthModel
+
+model = st.title("Boltzman Wealth Model")
+num_agents = st.slider(
+    "Choose how many agents to include in the model",
+    min_value=1,
+    max_value=100,
+    value=50,
+)
+num_ticks = st.slider(
+    "Select number of Simulation Runs", min_value=1, max_value=100, value=50
+)
+height = st.slider("Select Grid Height", min_value=10, max_value=100, step=10, value=15)
+width = st.slider("Select Grid Width", min_value=10, max_value=100, step=10, value=20)
+model = BoltzmannWealthModel(num_agents, height, width)
+
+
+status_text = st.empty()
+run = st.button("Run Simulation")
+
+
+if run:
+    tick = time.time()
+    step = 0
+    # init grid
+    df_grid = pd.DataFrame()
+    df_gini = pd.DataFrame({"step": [0], "gini": [-1]})
+    for x in range(width):
+        for y in range(height):
+            df_grid = pd.concat(
+                [df_grid, pd.DataFrame({"x": [x], "y": [y], "agent_count": 0})],
+                ignore_index=True,
+            )
+
+    heatmap = (
+        alt.Chart(df_grid)
+        .mark_point(size=100)
+        .encode(x="x", y="y", color=alt.Color("agent_count"))
+        .interactive()
+        .properties(width=800, height=600)
+    )
+
+    line = (
+        alt.Chart(df_gini)
+        .mark_line(point=True)
+        .encode(x="step", y="gini")
+        .properties(width=800, height=600)
+    )
+
+    # init progress bar
+    my_bar = st.progress(0, text="Simulation Progress")  # progress
+    placeholder = st.empty()
+    st.subheader("Agent Grid")
+    chart = st.altair_chart(heatmap)
+    st.subheader("Gini Values")
+    line_chart = st.altair_chart(line)
+
+    color_scale = alt.Scale(
+        domain=[0, 1, 2, 3, 4], range=["red", "cyan", "white", "white", "blue"]
+    )
+    for i in range(num_ticks):
+        model.step()
+        my_bar.progress((i / num_ticks), text="Simulation progress")
+        placeholder.text("Step = %d" % i)
+        for cell in model.grid.coord_iter():
+            cell_content, (x, y) = cell
+            agent_count = len(cell_content)
+            selected_row = df_grid[(df_grid["x"] == x) & (df_grid["y"] == y)]
+            df_grid.loc[selected_row.index, "agent_count"] = (
+                agent_count  # random.choice([1,2])
+            )
+
+        df_gini = pd.concat(
+            [
+                df_gini,
+                pd.DataFrame(
+                    {"step": [i], "gini": [model.datacollector.model_vars["Gini"][i]]}
+                ),
+            ]
+        )
+        # st.table(df_grid)
+        heatmap = (
+            alt.Chart(df_grid)
+            .mark_circle(size=100)
+            .encode(x="x", y="y", color=alt.Color("agent_count", scale=color_scale))
+            .interactive()
+            .properties(width=800, height=600)
+        )
+        chart.altair_chart(heatmap)
+
+        line = (
+            alt.Chart(df_gini)
+            .mark_line(point=True)
+            .encode(x="step", y="gini")
+            .properties(width=800, height=600)
+        )
+        line_chart.altair_chart(line)
+
+        time.sleep(0.01)
+
+    tock = time.time()
+    st.success(f"Simulation completed in {tock - tick:.2f} secs")
+
+    # st.subheader('Agent Grid')
+    # fig = px.imshow(agent_counts,labels={'color':'Agent Count'})
+    # st.plotly_chart(fig)
+    # st.subheader('Gini value over sim ticks (Plotly)')
+    # chart = st.line_chart(model.datacollector.model_vars['Gini'])