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

mesa/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
+}

mesa/examples/basic/schelling/app.py

@@ -0,0 +1,42 @@
+import solara
+
+from mesa.examples.basic.schelling.model import Schelling
+from mesa.visualization import (
+    Slider,
+    SolaraViz,
+    make_plot_measure,
+    make_space_matplotlib,
+)
+
+
+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

mesa/examples/basic/schelling/model.py

@@ -0,0 +1,59 @@
+import mesa
+from mesa import Model
+from mesa.examples.basic.schelling.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)

mesa/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.

mesa/examples/basic/virus_on_network/agents.py

@@ -0,0 +1,69 @@
+from enum import Enum
+
+from mesa import Agent
+
+
+class State(Enum):
+    SUSCEPTIBLE = 0
+    INFECTED = 1
+    RESISTANT = 2
+
+
+class VirusAgent(Agent):
+    """Individual Agent definition and its properties/interaction methods."""
+
+    def __init__(
+        self,
+        model,
+        initial_state,
+        virus_spread_chance,
+        virus_check_frequency,
+        recovery_chance,
+        gain_resistance_chance,
+    ):
+        super().__init__(model)
+
+        self.state = initial_state
+
+        self.virus_spread_chance = virus_spread_chance
+        self.virus_check_frequency = virus_check_frequency
+        self.recovery_chance = recovery_chance
+        self.gain_resistance_chance = gain_resistance_chance
+
+    def try_to_infect_neighbors(self):
+        neighbors_nodes = self.model.grid.get_neighborhood(
+            self.pos, include_center=False
+        )
+        susceptible_neighbors = [
+            agent
+            for agent in self.model.grid.get_cell_list_contents(neighbors_nodes)
+            if agent.state is State.SUSCEPTIBLE
+        ]
+        for a in susceptible_neighbors:
+            if self.random.random() < self.virus_spread_chance:
+                a.state = State.INFECTED
+
+    def try_gain_resistance(self):
+        if self.random.random() < self.gain_resistance_chance:
+            self.state = State.RESISTANT
+
+    def try_remove_infection(self):
+        # Try to remove
+        if self.random.random() < self.recovery_chance:
+            # Success
+            self.state = State.SUSCEPTIBLE
+            self.try_gain_resistance()
+        else:
+            # Failed
+            self.state = State.INFECTED
+
+    def try_check_situation(self):
+        if (self.random.random() < self.virus_check_frequency) and (
+            self.state is State.INFECTED
+        ):
+            self.try_remove_infection()
+
+    def step(self):
+        if self.state is State.INFECTED:
+            self.try_to_infect_neighbors()
+        self.try_check_situation()

mesa/examples/basic/virus_on_network/app.py

@@ -0,0 +1,136 @@
+import math
+
+import solara
+from matplotlib.figure import Figure
+from matplotlib.ticker import MaxNLocator
+
+from mesa.examples.basic.virus_on_network.model import (
+    State,
+    VirusOnNetwork,
+    number_infected,
+)
+from mesa.visualization import Slider, SolaraViz, make_space_matplotlib
+
+
+def agent_portrayal(graph):
+    def get_agent(node):
+        return graph.nodes[node]["agent"][0]
+
+    edge_width = []
+    edge_color = []
+    for u, v in graph.edges():
+        agent1 = get_agent(u)
+        agent2 = get_agent(v)
+        w = 2
+        ec = "#e8e8e8"
+        if State.RESISTANT in (agent1.state, agent2.state):
+            w = 3
+            ec = "black"
+        edge_width.append(w)
+        edge_color.append(ec)
+    node_color_dict = {
+        State.INFECTED: "tab:red",
+        State.SUSCEPTIBLE: "tab:green",
+        State.RESISTANT: "tab:gray",
+    }
+    node_color = [node_color_dict[get_agent(node).state] for node in graph.nodes()]
+    return {
+        "width": edge_width,
+        "edge_color": edge_color,
+        "node_color": node_color,
+    }
+
+
+def get_resistant_susceptible_ratio(model):
+    ratio = model.resistant_susceptible_ratio()
+    ratio_text = r"$\infty$" if ratio is math.inf else f"{ratio:.2f}"
+    infected_text = str(number_infected(model))
+
+    return f"Resistant/Susceptible Ratio: {ratio_text}<br>Infected Remaining: {infected_text}"
+
+
+def make_plot(model):
+    # This is for the case when we want to plot multiple measures in 1 figure.
+    fig = Figure()
+    ax = fig.subplots()
+    measures = ["Infected", "Susceptible", "Resistant"]
+    colors = ["tab:red", "tab:green", "tab:gray"]
+    for i, m in enumerate(measures):
+        color = colors[i]
+        df = model.datacollector.get_model_vars_dataframe()
+        ax.plot(df.loc[:, m], label=m, color=color)
+    fig.legend()
+    # Set integer x axis
+    ax.xaxis.set_major_locator(MaxNLocator(integer=True))
+    ax.set_xlabel("Step")
+    ax.set_ylabel("Number of Agents")
+    return solara.FigureMatplotlib(fig)
+
+
+model_params = {
+    "num_nodes": Slider(
+        label="Number of agents",
+        value=10,
+        min=10,
+        max=100,
+        step=1,
+    ),
+    "avg_node_degree": Slider(
+        label="Avg Node Degree",
+        value=3,
+        min=3,
+        max=8,
+        step=1,
+    ),
+    "initial_outbreak_size": Slider(
+        label="Initial Outbreak Size",
+        value=1,
+        min=1,
+        max=10,
+        step=1,
+    ),
+    "virus_spread_chance": Slider(
+        label="Virus Spread Chance",
+        value=0.4,
+        min=0.0,
+        max=1.0,
+        step=0.1,
+    ),
+    "virus_check_frequency": Slider(
+        label="Virus Check Frequency",
+        value=0.4,
+        min=0.0,
+        max=1.0,
+        step=0.1,
+    ),
+    "recovery_chance": Slider(
+        label="Recovery Chance",
+        value=0.3,
+        min=0.0,
+        max=1.0,
+        step=0.1,
+    ),
+    "gain_resistance_chance": Slider(
+        label="Gain Resistance Chance",
+        value=0.5,
+        min=0.0,
+        max=1.0,
+        step=0.1,
+    ),
+}
+
+SpacePlot = make_space_matplotlib(agent_portrayal)
+
+model1 = VirusOnNetwork()
+
+page = SolaraViz(
+    model1,
+    [
+        SpacePlot,
+        make_plot,
+        # get_resistant_susceptible_ratio,  # TODO: Fix and uncomment
+    ],
+    model_params=model_params,
+    name="Virus Model",
+)
+page  # noqa

mesa/examples/basic/virus_on_network/model.py

@@ -0,0 +1,96 @@
+import math
+
+import networkx as nx
+
+import mesa
+from mesa import Model
+from mesa.examples.basic.virus_on_network.agents import State, VirusAgent
+
+
+def number_state(model, state):
+    return sum(1 for a in model.grid.get_all_cell_contents() if a.state is state)
+
+
+def number_infected(model):
+    return number_state(model, State.INFECTED)
+
+
+def number_susceptible(model):
+    return number_state(model, State.SUSCEPTIBLE)
+
+
+def number_resistant(model):
+    return number_state(model, State.RESISTANT)
+
+
+class VirusOnNetwork(Model):
+    """A virus model with some number of agents."""
+
+    def __init__(
+        self,
+        num_nodes=10,
+        avg_node_degree=3,
+        initial_outbreak_size=1,
+        virus_spread_chance=0.4,
+        virus_check_frequency=0.4,
+        recovery_chance=0.3,
+        gain_resistance_chance=0.5,
+        seed=None,
+    ):
+        super().__init__(seed=seed)
+        self.num_nodes = num_nodes
+        prob = avg_node_degree / self.num_nodes
+        self.G = nx.erdos_renyi_graph(n=self.num_nodes, p=prob)
+        self.grid = mesa.space.NetworkGrid(self.G)
+
+        self.initial_outbreak_size = (
+            initial_outbreak_size if initial_outbreak_size <= num_nodes else num_nodes
+        )
+        self.virus_spread_chance = virus_spread_chance
+        self.virus_check_frequency = virus_check_frequency
+        self.recovery_chance = recovery_chance
+        self.gain_resistance_chance = gain_resistance_chance
+
+        self.datacollector = mesa.DataCollector(
+            {
+                "Infected": number_infected,
+                "Susceptible": number_susceptible,
+                "Resistant": number_resistant,
+                "R over S": self.resistant_susceptible_ratio,
+            }
+        )
+
+        # Create agents
+        for node in self.G.nodes():
+            a = VirusAgent(
+                self,
+                State.SUSCEPTIBLE,
+                self.virus_spread_chance,
+                self.virus_check_frequency,
+                self.recovery_chance,
+                self.gain_resistance_chance,
+            )
+
+            # Add the agent to the node
+            self.grid.place_agent(a, node)
+
+        # Infect some nodes
+        infected_nodes = self.random.sample(list(self.G), self.initial_outbreak_size)
+        for a in self.grid.get_cell_list_contents(infected_nodes):
+            a.state = State.INFECTED
+
+        self.running = True
+        self.datacollector.collect(self)
+
+    def resistant_susceptible_ratio(self):
+        try:
+            return number_state(self, State.RESISTANT) / number_state(
+                self, State.SUSCEPTIBLE
+            )
+        except ZeroDivisionError:
+            return math.inf
+
+    def step(self):
+        self.agents.shuffle_do("step")
+        # collect data
+        self.datacollector.collect(self)

mesa/experimental/__init__.py

@@ -2,6 +2,12 @@
 
 from mesa.experimental import cell_space
 
-from .solara_viz import JupyterViz, Slider, SolaraViz, make_text
+try:
+    from .solara_viz import JupyterViz, Slider, SolaraViz, make_text
 
-__all__ = ["cell_space", "JupyterViz", "SolaraViz", "make_text", "Slider"]
+    __all__ = ["cell_space", "JupyterViz", "Slider", "SolaraViz", "make_text"]
+except ImportError:
+    print(
+        "Could not import SolaraViz. If you need it, install with 'pip install --pre mesa[viz]'"
+    )
+    __all__ = ["cell_space"]

mesa/experimental/cell_space/cell.py

@@ -211,3 +211,12 @@ class Cell:
         self._mesa_property_layers[property_name].modify_cell(
             self.coordinate, operation, value
         )
+
+    def __getstate__(self):
+        """Return state of the Cell with connections set to empty."""
+        # fixme, once we shift to 3.11, replace this with super. __getstate__
+        state = (self.__dict__, {k: getattr(self, k) for k in self.__slots__})
+        state[1][
+            "connections"
+        ] = {}  # replace this with empty connections to avoid infinite recursion error in pickle/deepcopy
+        return state