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

examples/basic/conways_game_of_life/Readme.md

@@ -0,0 +1,35 @@
+# Conway's Game Of "Life"
+
+## Summary
+
+[The Game of Life](https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life), also known simply as "Life", is a cellular automaton devised by the British mathematician John Horton Conway in 1970.
+
+The "game" is a zero-player game, meaning that its evolution is determined by its initial state, requiring no further input by a human. One interacts with the Game of "Life" by creating an initial configuration and observing how it evolves, or, for advanced "players", by creating patterns with particular properties.
+
+
+## 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 ``run``.
+
+## Files
+
+* ``agents.py``: Defines the behavior of an individual cell, which can be in two states: DEAD or ALIVE.
+* ``model.py``: Defines the model itself, initialized with a random configuration of alive and dead cells.
+* ``portrayal.py``: Describes for the front end how to render a cell.
+* ``st_app.py``: Defines an interactive visualization using Streamlit.
+
+## Optional
+
+*  ``conways_game_of_life/st_app.py``: can be used to run the simulation via the streamlit interface.
+* For this some additional packages like ``streamlit`` and ``altair`` needs to be installed.
+* Once installed, the app can be opened in the browser using : ``streamlit run st_app.py``
+
+
+## Further Reading
+[Conway's Game of Life](https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life)

examples/basic/conways_game_of_life/agents.py

@@ -0,0 +1,47 @@
+from mesa import Agent
+
+
+class Cell(Agent):
+    """Represents a single ALIVE or DEAD cell in the simulation."""
+
+    DEAD = 0
+    ALIVE = 1
+
+    def __init__(self, pos, model, init_state=DEAD):
+        """Create a cell, in the given state, at the given x, y position."""
+        super().__init__(model)
+        self.x, self.y = pos
+        self.state = init_state
+        self._nextState = None
+
+    @property
+    def isAlive(self):
+        return self.state == self.ALIVE
+
+    @property
+    def neighbors(self):
+        return self.model.grid.iter_neighbors((self.x, self.y), True)
+
+    def determine_state(self):
+        """Compute if the cell will be dead or alive at the next tick.  This is
+        based on the number of alive or dead neighbors.  The state is not
+        changed here, but is just computed and stored in self._nextState,
+        because our current state may still be necessary for our neighbors
+        to calculate their next state.
+        """
+        # Get the neighbors and apply the rules on whether to be alive or dead
+        # at the next tick.
+        live_neighbors = sum(neighbor.isAlive for neighbor in self.neighbors)
+
+        # Assume nextState is unchanged, unless changed below.
+        self._nextState = self.state
+        if self.isAlive:
+            if live_neighbors < 2 or live_neighbors > 3:
+                self._nextState = self.DEAD
+        else:
+            if live_neighbors == 3:
+                self._nextState = self.ALIVE
+
+    def assume_state(self):
+        """Set the state to the new computed state -- computed in step()."""
+        self.state = self._nextState

examples/basic/conways_game_of_life/model.py

@@ -0,0 +1,32 @@
+from mesa import Model
+from mesa.space import SingleGrid
+
+from .agents import Cell
+
+
+class ConwaysGameOfLife(Model):
+    """Represents the 2-dimensional array of cells in Conway's Game of Life."""
+
+    def __init__(self, width=50, height=50):
+        """Create a new playing area of (width, height) cells."""
+        super().__init__()
+        # Use a simple grid, where edges wrap around.
+        self.grid = SingleGrid(width, height, torus=True)
+
+        # Place a cell at each location, with some initialized to
+        # ALIVE and some to DEAD.
+        for _contents, (x, y) in self.grid.coord_iter():
+            cell = Cell((x, y), self)
+            if self.random.random() < 0.1:
+                cell.state = cell.ALIVE
+            self.grid.place_agent(cell, (x, y))
+
+        self.running = True
+
+    def step(self):
+        """Perform the model step in two stages:
+        - First, all cells assume their next state (whether they will be dead or alive)
+        - Then, all cells change state to their next state.
+        """
+        self.agents.do("determine_state")
+        self.agents.do("assume_state")

examples/basic/conways_game_of_life/portrayal.py

@@ -0,0 +1,18 @@
+def portrayCell(cell):
+    """This function is registered with the visualization server to be called
+    each tick to indicate how to draw the cell in its current state.
+    :param cell:  the cell in the simulation
+    :return: the portrayal dictionary.
+    """
+    if cell is None:
+        raise AssertionError
+    return {
+        "Shape": "rect",
+        "w": 1,
+        "h": 1,
+        "Filled": "true",
+        "Layer": 0,
+        "x": cell.x,
+        "y": cell.y,
+        "Color": "black" if cell.isAlive else "white",
+    }

examples/basic/conways_game_of_life/requirements.txt

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

examples/basic/conways_game_of_life/server.py

@@ -0,0 +1,11 @@
+import mesa
+
+from .model import ConwaysGameOfLife
+from .portrayal import portrayCell
+
+# Make a world that is 50x50, on a 250x250 display.
+canvas_element = mesa.visualization.CanvasGrid(portrayCell, 50, 50, 250, 250)
+
+server = mesa.visualization.ModularServer(
+    ConwaysGameOfLife, [canvas_element], "Game of Life", {"height": 50, "width": 50}
+)

examples/basic/conways_game_of_life/st_app.py

@@ -0,0 +1,71 @@
+import time
+
+import altair as alt
+import numpy as np
+import pandas as pd
+import streamlit as st
+from model import ConwaysGameOfLife
+
+model = st.title("Conway's Game of Life")
+num_ticks = st.slider("Select number of Steps", 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 = ConwaysGameOfLife(height, width)
+
+col1, col2, col3 = st.columns(3)
+status_text = st.empty()
+# step_mode = st.checkbox('Run Step-by-Step')
+run = st.button("Run Simulation")
+
+
+if run:
+    tick = time.time()
+    step = 0
+    # init grid
+    df_grid = pd.DataFrame()
+    agent_counts = np.zeros((model.grid.width, model.grid.height))
+    for x in range(width):
+        for y in range(height):
+            df_grid = pd.concat(
+                [df_grid, pd.DataFrame({"x": [x], "y": [y], "state": [0]})],
+                ignore_index=True,
+            )
+
+    heatmap = (
+        alt.Chart(df_grid)
+        .mark_point(size=100)
+        .encode(x="x", y="y", color=alt.Color("state"))
+        .interactive()
+        .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, use_container_width=True)
+    color_scale = alt.Scale(domain=[0, 1], range=["red", "yellow"])
+    for i in range(num_ticks):
+        model.step()
+        my_bar.progress((i / num_ticks), text="Simulation progress")
+        placeholder.text("Step = %d" % i)
+        for contents, (x, y) in model.grid.coord_iter():
+            # print('x:',x,'y:',y, 'state:',contents)
+            selected_row = df_grid[(df_grid["x"] == x) & (df_grid["y"] == y)]
+            df_grid.loc[selected_row.index, "state"] = (
+                contents.state
+            )  # random.choice([1,2])
+
+        heatmap = (
+            alt.Chart(df_grid)
+            .mark_circle(size=100)
+            .encode(x="x", y="y", color=alt.Color("state", scale=color_scale))
+            .interactive()
+            .properties(width=800, height=600)
+        )
+        chart.altair_chart(heatmap)
+
+        time.sleep(0.1)
+
+    tock = time.time()
+    st.success(f"Simulation completed in {tock - tick:.2f} secs")

examples/basic/schelling/README.md

@@ -0,0 +1,47 @@
+# Schelling Segregation Model
+
+## Summary
+
+The Schelling segregation model is a classic agent-based model, demonstrating how even a mild preference for similar neighbors can lead to a much higher degree of segregation than we would intuitively expect. The model consists of agents on a square grid, where each grid cell can contain at most one agent. Agents come in two colors: red and blue. They are happy if a certain number of their eight possible neighbors are of the same color, and unhappy otherwise. Unhappy agents will pick a random empty cell to move to each step, until they are happy. The model keeps running until there are no unhappy agents.
+
+By default, the number of similar neighbors the agents need to be happy is set to 3. That means the agents would be perfectly happy with a majority of their neighbors being of a different color (e.g. a Blue agent would be happy with five Red neighbors and three Blue ones). Despite this, the model consistently leads to a high degree of segregation, with most agents ending up with no neighbors of a different color.
+
+## 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 run the model interactively, in this directory, run the following command
+
+```
+    $ solara run app.py
+```
+
+Then open your browser to [http://127.0.0.1:8765/](http://127.0.0.1:8765/) and click the Play button.
+
+To view and run some example model analyses, launch the IPython Notebook and open ``analysis.ipynb``. Visualizing the analysis also requires [matplotlib](http://matplotlib.org/).
+
+## How to Run without the GUI
+
+To run the model with the grid displayed as an ASCII text, run `python run_ascii.py` in this directory.
+
+## Files
+
+* ``app.py``: Code for the interactive visualization.
+* ``schelling.py``: Contains the agent class, and the overall model class.
+* ``analysis.ipynb``: Notebook demonstrating how to run experiments and parameter sweeps on the model.
+
+## Further Reading
+
+Schelling's original paper describing the model:
+
+[Schelling, Thomas C. Dynamic Models of Segregation. Journal of Mathematical Sociology. 1971, Vol. 1, pp 143-186.](https://www.stat.berkeley.edu/~aldous/157/Papers/Schelling_Seg_Models.pdf)
+
+An interactive, browser-based explanation and implementation:
+
+[Parable of the Polygons](http://ncase.me/polygons/), by Vi Hart and Nicky Case.

examples/basic/schelling/agents.py

@@ -0,0 +1,26 @@
+from mesa import Agent, Model
+
+
+class SchellingAgent(Agent):
+    """Schelling segregation agent."""
+
+    def __init__(self, model: Model, agent_type: int) -> None:
+        """Create a new Schelling agent.
+
+        Args:
+           agent_type: Indicator for the agent's type (minority=1, majority=0)
+        """
+        super().__init__(model)
+        self.type = agent_type
+
+    def step(self) -> None:
+        neighbors = self.model.grid.iter_neighbors(
+            self.pos, moore=True, radius=self.model.radius
+        )
+        similar = sum(1 for neighbor in neighbors if neighbor.type == self.type)
+
+        # If unhappy, move:
+        if similar < self.model.homophily:
+            self.model.grid.move_to_empty(self)
+        else:
+            self.model.happy += 1

examples/basic/schelling/analysis.ipynb

@@ -0,0 +1,205 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Schelling Segregation Model\n",
+    "\n",
+    "## Background\n",
+    "\n",
+    "The Schelling (1971) segregation model is a classic of agent-based modeling, demonstrating how agents following simple rules lead to the emergence of qualitatively different macro-level outcomes. Agents are randomly placed on a grid. There are two types of agents, one constituting the majority and the other the minority. All agents want a certain number (generally, 3) of their 8 surrounding neighbors to be of the same type in order for them to be happy. Unhappy agents will move to a random available grid space. While individual agents do not have a preference for a segregated outcome (e.g. they would be happy with 3 similar neighbors and 5 different ones), the aggregate outcome is nevertheless heavily segregated.\n",
+    "\n",
+    "## Implementation\n",
+    "\n",
+    "This is a demonstration of running a Mesa model in an IPython Notebook. The actual model and agent code are implemented in Schelling.py, in the same directory as this notebook. Below, we will import the model class, instantiate it, run it, and plot the time series of the number of happy agents."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "import pandas as pd\n",
+    "\n",
+    "%matplotlib inline\n",
+    "\n",
+    "from model import Schelling"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now we instantiate a model instance: a 10x10 grid, with an 80% change of an agent being placed in each cell, approximately 20% of agents set as minorities, and agents wanting at least 3 similar neighbors."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": "model = Schelling(height=10, width=10, homophily=3, density=0.8, minority_pc=0.2)",
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We want to run the model until all the agents are happy with where they are. However, there's no guarantee that a given model instantiation will *ever* settle down. So let's run it for either 100 steps or until it stops on its own, whichever comes first:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "while model.running and model.steps < 100:\n",
+    "    model.step()\n",
+    "print(model.steps)  # Show how many steps have actually run"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The model has a DataCollector object, which checks and stores how many agents are happy at the end of each step. It can also generate a pandas DataFrame of the data it has collected:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "model_out = model.datacollector.get_model_vars_dataframe()"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "model_out.head()"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Finally, we can plot the 'happy' series:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "model_out.happy.plot()"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Effect of Homophily on happiness\n",
+    "\n",
+    "Now, we can do a parameter sweep to see how happiness changes with homophily.\n",
+    "\n",
+    "First, we create a function which takes a model instance and returns what fraction of agents are segregated -- that is, have no neighbors of the opposite type."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": "from mesa.batchrunner import batch_run",
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now, we set up the batch run, with a dictionary of fixed and changing parameters. Let's hold everything fixed except for Homophily."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "fixed_params = {\"height\": 10, \"width\": 10, \"density\": 0.8, \"minority_pc\": 0.2}\n",
+    "variable_parms = {\"homophily\": range(1, 9)}\n",
+    "all_params = fixed_params | variable_parms"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "results = batch_run(\n",
+    "    Schelling,\n",
+    "    parameters=all_params,\n",
+    "    iterations=10,\n",
+    "    max_steps=200,\n",
+    ")"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "metadata": {},
+   "cell_type": "code",
+   "source": [
+    "df = pd.DataFrame(results)\n",
+    "df"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "code",
+   "metadata": {},
+   "source": [
+    "plt.scatter(df.homophily, df.happy)\n",
+    "plt.xlabel(\"Homophily\")\n",
+    "plt.ylabel(\"Happy Agents\")\n",
+    "plt.grid()\n",
+    "plt.title(\"Effect of Homophily on segregation\")\n",
+    "plt.show()"
+   ],
+   "outputs": [],
+   "execution_count": null
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.9"
+  },
+  "widgets": {
+   "state": {},
+   "version": "1.1.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 1
+}

examples/basic/schelling/app.py

@@ -0,0 +1,43 @@
+import solara
+
+from mesa.visualization import (
+    Slider,
+    SolaraViz,
+    make_plot_measure,
+    make_space_matplotlib,
+)
+
+from .model import Schelling
+
+
+def get_happy_agents(model):
+    """Display a text count of how many happy agents there are."""
+    return solara.Markdown(f"**Happy agents: {model.happy}**")
+
+
+def agent_portrayal(agent):
+    return {"color": "tab:orange" if agent.type == 0 else "tab:blue"}
+
+
+model_params = {
+    "density": Slider("Agent density", 0.8, 0.1, 1.0, 0.1),
+    "minority_pc": Slider("Fraction minority", 0.2, 0.0, 1.0, 0.05),
+    "homophily": Slider("Homophily", 3, 0, 8, 1),
+    "width": 20,
+    "height": 20,
+}
+
+model1 = Schelling(20, 20, 0.8, 0.2, 3)
+
+HappyPlot = make_plot_measure("happy")
+
+page = SolaraViz(
+    model1,
+    components=[
+        make_space_matplotlib(agent_portrayal),
+        make_plot_measure("happy"),
+        get_happy_agents,
+    ],
+    model_params=model_params,
+)
+page  # noqa

examples/basic/schelling/model.py

@@ -0,0 +1,60 @@
+import mesa
+from mesa import Model
+
+from .agents import SchellingAgent
+
+
+class Schelling(Model):
+    """Model class for the Schelling segregation model."""
+
+    def __init__(
+        self,
+        height=20,
+        width=20,
+        homophily=3,
+        radius=1,
+        density=0.8,
+        minority_pc=0.2,
+        seed=None,
+    ):
+        """Create a new Schelling model.
+
+        Args:
+            width, height: Size of the space.
+            density: Initial Chance for a cell to populated
+            minority_pc: Chances for an agent to be in minority class
+            homophily: Minimum number of agents of same class needed to be happy
+            radius: Search radius for checking similarity
+            seed: Seed for Reproducibility
+        """
+        super().__init__(seed=seed)
+        self.homophily = homophily
+        self.radius = radius
+
+        self.grid = mesa.space.SingleGrid(width, height, torus=True)
+
+        self.happy = 0
+        self.datacollector = mesa.DataCollector(
+            model_reporters={"happy": "happy"},  # Model-level count of happy agents
+        )
+
+        # Set up agents
+        # We use a grid iterator that returns
+        # the coordinates of a cell as well as
+        # its contents. (coord_iter)
+        for _, pos in self.grid.coord_iter():
+            if self.random.random() < density:
+                agent_type = 1 if self.random.random() < minority_pc else 0
+                agent = SchellingAgent(self, agent_type)
+                self.grid.place_agent(agent, pos)
+
+        self.datacollector.collect(self)
+
+    def step(self):
+        """Run one step of the model."""
+        self.happy = 0  # Reset counter of happy agents
+        self.agents.shuffle_do("step")
+
+        self.datacollector.collect(self)
+
+        self.running = self.happy != len(self.agents)

examples/basic/virus_on_network/README.md

@@ -0,0 +1,61 @@
+# Virus on a Network
+
+## Summary
+
+This model is based on the NetLogo model "Virus on Network". It demonstrates the spread of a virus through a network and follows the SIR model, commonly seen in epidemiology.
+
+The SIR model is one of the simplest compartmental models, and many models are derivatives of this basic form. The model consists of three compartments:
+
+S: The number of susceptible individuals. When a susceptible and an infectious individual come into "infectious contact", the susceptible individual contracts the disease and transitions to the infectious compartment.
+I: The number of infectious individuals. These are individuals who have been infected and are capable of infecting susceptible individuals.
+R for the number of removed (and immune) or deceased individuals. These are individuals who have been infected and have either recovered from the disease and entered the removed compartment, or died. It is assumed that the number of deaths is negligible with respect to the total population. This compartment may also be called "recovered" or "resistant".
+
+For more information about this model, read the NetLogo's web page: http://ccl.northwestern.edu/netlogo/models/VirusonaNetwork.
+
+JavaScript library used in this example to render the network: [d3.js](https://d3js.org/).
+
+## 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 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.
+
+or
+
+Directly run the file ``run.py`` in the terminal. e.g.
+
+```
+    $ python run.py
+```
+
+
+## Files
+
+* ``model.py``: Contains the agent class, and the overall model class.
+* ``agents.py``: Contains the agent class.
+* ``app.py``: Contains the code for the interactive Solara visualization.
+
+## 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
+
+
+[Stonedahl, F. and Wilensky, U. (2008). NetLogo Virus on a Network model](http://ccl.northwestern.edu/netlogo/models/VirusonaNetwork).
+Center for Connected Learning and Computer-Based Modeling, Northwestern University, Evanston, IL.
+
+
+[Wilensky, U. (1999). NetLogo](http://ccl.northwestern.edu/netlogo/)
+Center for Connected Learning and Computer-Based Modeling, Northwestern University, Evanston, IL.