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

mesa/__init__.py

@@ -24,7 +24,7 @@ __all__ = [
 ]
 
 __title__ = "mesa"
-__version__ = "3.0.0b2"
+__version__ = "3.0.0rc0"
 __license__ = "Apache 2.0"
 _this_year = datetime.datetime.now(tz=datetime.timezone.utc).date().year
 __copyright__ = f"Copyright {_this_year} Project Mesa Team"

mesa/batchrunner.py

@@ -1,4 +1,29 @@
-"""batchrunner for running a factorial experiment design over a model."""
+"""batchrunner for running a factorial experiment design over a model.
+
+To take advantage of parallel execution of experiments, `batch_run` uses
+multiprocessing if ``number_processes`` is larger than 1. It is strongly advised
+to only run in parallel using a normal python file (so don't try to do it in a
+jupyter notebook). Moreover, best practice when using multiprocessing is to
+put the code inside an ``if __name__ == '__main__':`` code black as shown below::
+
+    from mesa.batchrunner import batch_run
+
+    params = {"width": 10, "height": 10, "N": range(10, 500, 10)}
+
+    if __name__ == '__main__':
+        results = batch_run(
+            MoneyModel,
+            parameters=params,
+            iterations=5,
+            max_steps=100,
+            number_processes=None,
+            data_collection_period=1,
+            display_progress=True,
+        )
+
+
+
+"""
 
 import itertools
 import multiprocessing

mesa/examples/README.md

@@ -1,37 +1,37 @@
 # Mesa core examples
-This folder contains a collection of example models built using Mesa. These core models are maintained by the Mesa team and are intended to demonstrate the capabilities of Mesa.
+These examples are a collection of classic agent based models built using Mesa. These core examples are maintained by the Mesa team and are intended to demonstrate the capabilities of Mesa.
 
 More user examples and showcases can be found in the [mesa-examples](https://github.com/projectmesa/mesa-examples) repository.
 
 ## Basic Examples
 The basic examples are relatively simple and only use stable Mesa features. They are good starting points for learning how to use Mesa.
 
-### [Boltzmann Wealth Model](basic/boltzmann_wealth_model)
+### [Boltzmann Wealth Model](examples/basic/boltzmann_wealth_model)
 Completed code to go along with the [tutorial](https://mesa.readthedocs.io/latest/tutorials/intro_tutorial.html) on making a simple model of how a highly-skewed wealth distribution can emerge from simple rules.
 
-### [Boids Flockers Model](basic/boid_flockers)
+### [Boids Flockers Model](examples/basic/boid_flockers)
 [Boids](https://en.wikipedia.org/wiki/Boids)-style flocking model, demonstrating the use of agents moving through a continuous space following direction vectors.
 
-### [Conway's Game of Life](basic/conways_game_of_life)
+### [Conway's Game of Life](examples/basic/conways_game_of_life)
 Implementation of [Conway's Game of Life](https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life), a cellular automata where simple rules can give rise to complex patterns.
 
-### [Schelling Segregation Model](basic/schelling)
+### [Schelling Segregation Model](examples/basic/schelling)
 Mesa implementation of the classic [Schelling segregation](http://nifty.stanford.edu/2014/mccown-schelling-model-segregation/) model.
 
-### [Virus on a Network Model](basic/virus_on_network)
+### [Virus on a Network Model](examples/basic/virus_on_network)
 This model is based on the NetLogo [Virus on a Network](https://ccl.northwestern.edu/netlogo/models/VirusonaNetwork) model.
 
 ## Advanced Examples
 The advanced examples are more complex and may use experimental Mesa features. They are good starting points for learning how to build more complex models.
 
-### [Epstein Civil Violence Model](advanced/epstein_civil_violence)
-Joshua Epstein's [model](http://www.uvm.edu/~pdodds/files/papers/others/2002/epstein2002a.pdf) of how a decentralized uprising can be suppressed or reach a critical mass of support.
+### [Epstein Civil Violence Model](examples/advanced/epstein_civil_violence)
+Joshua Epstein's [model](https://www.pnas.org/doi/10.1073/pnas.092080199) of how a decentralized uprising can be suppressed or reach a critical mass of support.
 
-### [Demographic Prisoner's Dilemma on a Grid](advanced/pd_grid)
+### [Demographic Prisoner's Dilemma on a Grid](examples/advanced/pd_grid)
 Grid-based demographic prisoner's dilemma model, demonstrating how simple rules can lead to the emergence of widespread cooperation -- and how a model activation regime can change its outcome.
 
-### [Sugarscape Model with Traders](advanced/sugarscape_g1mt)
+### [Sugarscape Model with Traders](examples/advanced/sugarscape_g1mt)
 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 how emergent price equilibrium can happen via decentralized dynamics.
 
-### [Wolf-Sheep Predation Model](advanced/wolf_sheep)
+### [Wolf-Sheep Predation Model](examples/advanced/wolf_sheep)
 Implementation of an ecological model of predation and reproduction, based on the NetLogo [Wolf Sheep Predation](http://ccl.northwestern.edu/netlogo/models/WolfSheepPredation) model.

mesa/examples/advanced/epstein_civil_violence/agents.py

@@ -1,18 +1,29 @@
 import math
+from enum import Enum
 
 import mesa
 
 
+class CitizenState(Enum):
+    ACTIVE = 1
+    QUIET = 2
+    ARRESTED = 3
+
+
 class EpsteinAgent(mesa.experimental.cell_space.CellAgent):
     def update_neighbors(self):
         """
         Look around and see who my neighbors are
         """
         self.neighborhood = self.cell.get_neighborhood(radius=self.vision)
-
         self.neighbors = self.neighborhood.agents
         self.empty_neighbors = [c for c in self.neighborhood if c.is_empty]
 
+    def move(self):
+        if self.model.movement and self.empty_neighbors:
+            new_pos = self.random.choice(self.empty_neighbors)
+            self.move_to(new_pos)
+
 
 class Citizen(EpsteinAgent):
     """
@@ -38,13 +49,7 @@ class Citizen(EpsteinAgent):
     """
 
     def __init__(
-        self,
-        model,
-        hardship,
-        regime_legitimacy,
-        risk_aversion,
-        threshold,
-        vision,
+        self, model, regime_legitimacy, threshold, vision, arrest_prob_constant
     ):
         """
         Create a new Citizen.
@@ -62,16 +67,21 @@ class Citizen(EpsteinAgent):
             model: model instance
         """
         super().__init__(model)
-        self.hardship = hardship
+        self.hardship = self.random.random()
+        self.risk_aversion = self.random.random()
         self.regime_legitimacy = regime_legitimacy
-        self.risk_aversion = risk_aversion
         self.threshold = threshold
-        self.condition = "Quiescent"
+        self.state = CitizenState.QUIET
         self.vision = vision
         self.jail_sentence = 0
         self.grievance = self.hardship * (1 - self.regime_legitimacy)
+        self.arrest_prob_constant = arrest_prob_constant
         self.arrest_probability = None
 
+        self.neighborhood = []
+        self.neighbors = []
+        self.empty_neighbors = []
+
     def step(self):
         """
         Decide whether to activate, then move if applicable.
@@ -81,32 +91,33 @@ class Citizen(EpsteinAgent):
             return  # no other changes or movements if agent is in jail.
         self.update_neighbors()
         self.update_estimated_arrest_probability()
+
         net_risk = self.risk_aversion * self.arrest_probability
-        if self.grievance - net_risk > self.threshold:
-            self.condition = "Active"
+        if (self.grievance - net_risk) > self.threshold:
+            self.state = CitizenState.ACTIVE
         else:
-            self.condition = "Quiescent"
+            self.state = CitizenState.QUIET
 
-        if self.model.movement and self.empty_neighbors:
-            new_cell = self.random.choice(self.empty_neighbors)
-            self.move_to(new_cell)
+        self.move()
 
     def update_estimated_arrest_probability(self):
         """
         Based on the ratio of cops to actives in my neighborhood, estimate the
         p(Arrest | I go active).
         """
-        cops_in_vision = len([c for c in self.neighbors if isinstance(c, Cop)])
-        actives_in_vision = 1.0  # citizen counts herself
-        for c in self.neighbors:
-            if (
-                isinstance(c, Citizen)
-                and c.condition == "Active"
-                and c.jail_sentence == 0
-            ):
+        cops_in_vision = 0
+        actives_in_vision = 1  # citizen counts herself
+        for neighbor in self.neighbors:
+            if isinstance(neighbor, Cop):
+                cops_in_vision += 1
+            elif neighbor.state == CitizenState.ACTIVE:
                 actives_in_vision += 1
+
+        # there is a body of literature on this equation
+        # the round is not in the pnas paper but without it, its impossible to replicate
+        # the dynamics shown there.
         self.arrest_probability = 1 - math.exp(
-            -1 * self.model.arrest_prob_constant * (cops_in_vision / actives_in_vision)
+            -1 * self.arrest_prob_constant * round(cops_in_vision / actives_in_vision)
         )
 
 
@@ -122,7 +133,7 @@ class Cop(EpsteinAgent):
             able to inspect
     """
 
-    def __init__(self, model, vision):
+    def __init__(self, model, vision, max_jail_term):
         """
         Create a new Cop.
         Args:
@@ -133,6 +144,7 @@ class Cop(EpsteinAgent):
         """
         super().__init__(model)
         self.vision = vision
+        self.max_jail_term = max_jail_term
 
     def step(self):
         """
@@ -142,17 +154,11 @@ class Cop(EpsteinAgent):
         self.update_neighbors()
         active_neighbors = []
         for agent in self.neighbors:
-            if (
-                isinstance(agent, Citizen)
-                and agent.condition == "Active"
-                and agent.jail_sentence == 0
-            ):
+            if isinstance(agent, Citizen) and agent.state == CitizenState.ACTIVE:
                 active_neighbors.append(agent)
         if active_neighbors:
             arrestee = self.random.choice(active_neighbors)
-            sentence = self.random.randint(0, self.model.max_jail_term)
-            arrestee.jail_sentence = sentence
-            arrestee.condition = "Quiescent"
-        if self.model.movement and self.empty_neighbors:
-            new_pos = self.random.choice(self.empty_neighbors)
-            self.move_to(new_pos)
+            arrestee.jail_sentence = self.random.randint(0, self.max_jail_term)
+            arrestee.state = CitizenState.ARRESTED
+
+        self.move()

mesa/examples/advanced/epstein_civil_violence/app.py

@@ -1,17 +1,23 @@
-from mesa.examples.advanced.epstein_civil_violence.agents import Citizen, Cop
+from mesa.examples.advanced.epstein_civil_violence.agents import (
+    Citizen,
+    CitizenState,
+    Cop,
+)
 from mesa.examples.advanced.epstein_civil_violence.model import EpsteinCivilViolence
 from mesa.visualization import (
     Slider,
     SolaraViz,
-    make_plot_measure,
-    make_space_matplotlib,
+    make_plot_component,
+    make_space_component,
 )
 
 COP_COLOR = "#000000"
-AGENT_QUIET_COLOR = "#648FFF"
-AGENT_REBEL_COLOR = "#FE6100"
-JAIL_COLOR = "#808080"
-JAIL_SHAPE = "rect"
+
+agent_colors = {
+    CitizenState.ACTIVE: "#FE6100",
+    CitizenState.QUIET: "#648FFF",
+    CitizenState.ARRESTED: "#808080",
+}
 
 
 def citizen_cop_portrayal(agent):
@@ -19,34 +25,24 @@ def citizen_cop_portrayal(agent):
         return
 
     portrayal = {
-        "size": 25,
-        "shape": "s",  # square marker
+        "size": 50,
     }
 
     if isinstance(agent, Citizen):
-        color = (
-            AGENT_QUIET_COLOR if agent.condition == "Quiescent" else AGENT_REBEL_COLOR
-        )
-        color = JAIL_COLOR if agent.jail_sentence else color
-        shape = JAIL_SHAPE if agent.jail_sentence else "circle"
-        portrayal["color"] = color
-        portrayal["shape"] = shape
-        if shape == "s":
-            portrayal["w"] = 0.9
-            portrayal["h"] = 0.9
-        else:
-            portrayal["r"] = 0.5
-            portrayal["filled"] = False
-        portrayal["layer"] = 0
-
+        portrayal["color"] = agent_colors[agent.state]
     elif isinstance(agent, Cop):
         portrayal["color"] = COP_COLOR
-        portrayal["r"] = 0.9
-        portrayal["layer"] = 1
 
     return portrayal
 
 
+def post_process(ax):
+    ax.set_aspect("equal")
+    ax.set_xticks([])
+    ax.set_yticks([])
+    ax.get_figure().set_size_inches(10, 10)
+
+
 model_params = {
     "height": 40,
     "width": 40,
@@ -58,8 +54,13 @@ model_params = {
     "max_jail_term": Slider("Max Jail Term", 30, 0, 50, 1),
 }
 
-space_component = make_space_matplotlib(citizen_cop_portrayal)
-chart_component = make_plot_measure(["Quiescent", "Active", "Jailed"])
+space_component = make_space_component(
+    citizen_cop_portrayal, post_process=post_process, draw_grid=False
+)
+
+chart_component = make_plot_component(
+    {state.name.lower(): agent_colors[state] for state in CitizenState}
+)
 
 epstein_model = EpsteinCivilViolence()
 

mesa/examples/advanced/epstein_civil_violence/model.py

@@ -1,5 +1,9 @@
 import mesa
-from mesa.examples.advanced.epstein_civil_violence.agents import Citizen, Cop
+from mesa.examples.advanced.epstein_civil_violence.agents import (
+    Citizen,
+    CitizenState,
+    Cop,
+)
 
 
 class EpsteinCivilViolence(mesa.Model):
@@ -7,7 +11,8 @@ class EpsteinCivilViolence(mesa.Model):
     Model 1 from "Modeling civil violence: An agent-based computational
     approach," by Joshua Epstein.
     http://www.pnas.org/content/99/suppl_3/7243.full
-    Attributes:
+
+    Args:
         height: grid height
         width: grid width
         citizen_density: approximate % of cells occupied by citizens.
@@ -45,61 +50,49 @@ class EpsteinCivilViolence(mesa.Model):
         seed=None,
     ):
         super().__init__(seed=seed)
-        self.width = width
-        self.height = height
-        self.citizen_density = citizen_density
-        self.cop_density = cop_density
-        self.citizen_vision = citizen_vision
-        self.cop_vision = cop_vision
-        self.legitimacy = legitimacy
-        self.max_jail_term = max_jail_term
-        self.active_threshold = active_threshold
-        self.arrest_prob_constant = arrest_prob_constant
         self.movement = movement
         self.max_iters = max_iters
-        self.iteration = 0
 
-        self.grid = mesa.experimental.cell_space.OrthogonalMooreGrid(
+        self.grid = mesa.experimental.cell_space.OrthogonalVonNeumannGrid(
             (width, height), capacity=1, torus=True, random=self.random
         )
 
         model_reporters = {
-            "Quiescent": lambda m: self.count_type_citizens(m, "Quiescent"),
-            "Active": lambda m: self.count_type_citizens(m, "Active"),
-            "Jailed": self.count_jailed,
-            "Cops": self.count_cops,
+            "active": CitizenState.ACTIVE.name,
+            "quiet": CitizenState.QUIET.name,
+            "arrested": CitizenState.ARRESTED.name,
         }
         agent_reporters = {
-            "x": lambda a: a.cell.coordinate[0],
-            "y": lambda a: a.cell.coordinate[1],
-            "breed": lambda a: type(a).__name__,
             "jail_sentence": lambda a: getattr(a, "jail_sentence", None),
-            "condition": lambda a: getattr(a, "condition", None),
             "arrest_probability": lambda a: getattr(a, "arrest_probability", None),
         }
         self.datacollector = mesa.DataCollector(
             model_reporters=model_reporters, agent_reporters=agent_reporters
         )
-        if self.cop_density + self.citizen_density > 1:
+        if cop_density + citizen_density > 1:
             raise ValueError("Cop density + citizen density must be less than 1")
 
         for cell in self.grid.all_cells:
-            if self.random.random() < self.cop_density:
-                cop = Cop(self, vision=self.cop_vision)
-                cop.move_to(cell)
+            klass = self.random.choices(
+                [Citizen, Cop, None],
+                cum_weights=[citizen_density, citizen_density + cop_density, 1],
+            )[0]
 
-            elif self.random.random() < (self.cop_density + self.citizen_density):
+            if klass == Cop:
+                cop = Cop(self, vision=cop_vision, max_jail_term=max_jail_term)
+                cop.move_to(cell)
+            elif klass == Citizen:
                 citizen = Citizen(
                     self,
-                    hardship=self.random.random(),
-                    regime_legitimacy=self.legitimacy,
-                    risk_aversion=self.random.random(),
-                    threshold=self.active_threshold,
-                    vision=self.citizen_vision,
+                    regime_legitimacy=legitimacy,
+                    threshold=active_threshold,
+                    vision=citizen_vision,
+                    arrest_prob_constant=arrest_prob_constant,
                 )
                 citizen.move_to(cell)
 
         self.running = True
+        self._update_counts()
         self.datacollector.collect(self)
 
     def step(self):
@@ -107,40 +100,15 @@ class EpsteinCivilViolence(mesa.Model):
         Advance the model by one step and collect data.
         """
         self.agents.shuffle_do("step")
-        # collect data
+        self._update_counts()
         self.datacollector.collect(self)
-        self.iteration += 1
-        if self.iteration > self.max_iters:
-            self.running = False
-
-    @staticmethod
-    def count_type_citizens(model, condition, exclude_jailed=True):
-        """
-        Helper method to count agents by Quiescent/Active.
-        """
-        citizens = model.agents_by_type[Citizen]
 
-        if exclude_jailed:
-            return len(
-                [
-                    c
-                    for c in citizens
-                    if (c.condition == condition) and (c.jail_sentence == 0)
-                ]
-            )
-        else:
-            return len([c for c in citizens if c.condition == condition])
+        if self.steps > self.max_iters:
+            self.running = False
 
-    @staticmethod
-    def count_jailed(model):
-        """
-        Helper method to count jailed agents.
-        """
-        return len([a for a in model.agents_by_type[Citizen] if a.jail_sentence > 0])
+    def _update_counts(self):
+        """Helper function for counting nr. of citizens in given state."""
+        counts = self.agents_by_type[Citizen].groupby("state").count()
 
-    @staticmethod
-    def count_cops(model):
-        """
-        Helper method to count jailed agents.
-        """
-        return len(model.agents_by_type[Cop])
+        for state in CitizenState:
+            setattr(self, state.name, counts.get(state, 0))

mesa/examples/advanced/pd_grid/app.py

@@ -3,7 +3,11 @@ Solara-based visualization for the Spatial Prisoner's Dilemma Model.
 """
 
 from mesa.examples.advanced.pd_grid.model import PdGrid
-from mesa.visualization import SolaraViz, make_plot_measure, make_space_matplotlib
+from mesa.visualization import (
+    SolaraViz,
+    make_plot_component,
+    make_space_component,
+)
 from mesa.visualization.UserParam import Slider
 
 
@@ -13,7 +17,7 @@ def pd_agent_portrayal(agent):
     """
     return {
         "color": "blue" if agent.move == "C" else "red",
-        "shape": "s",  # square marker
+        "marker": "s",  # square marker
         "size": 25,
     }
 
@@ -32,10 +36,10 @@ model_params = {
 
 
 # Create grid visualization component using Altair
-grid_viz = make_space_matplotlib(agent_portrayal=pd_agent_portrayal)
+grid_viz = make_space_component(agent_portrayal=pd_agent_portrayal)
 
 # Create plot for tracking cooperating agents over time
-plot_component = make_plot_measure("Cooperating_Agents")
+plot_component = make_plot_component("Cooperating_Agents")
 
 # Initialize model
 initial_model = PdGrid()

mesa/examples/advanced/sugarscape_g1mt/app.py

@@ -1,18 +1,10 @@
-import os.path
-import sys
-
-sys.path.insert(
-    0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../../../../"))
-)
-
-
 import numpy as np
 import solara
 from matplotlib.figure import Figure
-from sugarscape_g1mt.model import SugarscapeG1mt
-from sugarscape_g1mt.trader_agents import Trader
 
-from mesa.visualization import SolaraViz, make_plot_measure
+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):
@@ -63,8 +55,8 @@ model1 = SugarscapeG1mt(50, 50)
 
 page = SolaraViz(
     model1,
-    components=[SpaceDrawer, make_plot_measure(["Trader", "Price"])],
+    components=[SpaceDrawer, make_plot_component(["Trader", "Price"])],
     name="Sugarscape {G1, M, T}",
-    play_interval=1500,
+    play_interval=150,
 )
 page  # noqa

mesa/examples/advanced/wolf_sheep/app.py

@@ -3,13 +3,10 @@ from mesa.examples.advanced.wolf_sheep.model import WolfSheep
 from mesa.visualization import (
     Slider,
     SolaraViz,
-    make_plot_measure,
-    make_space_matplotlib,
+    make_plot_component,
+    make_space_component,
 )
 
-WOLF_COLOR = "#000000"
-SHEEP_COLOR = "#648FFF"
-
 
 def wolf_sheep_portrayal(agent):
     if agent is None:
@@ -17,23 +14,23 @@ def wolf_sheep_portrayal(agent):
 
     portrayal = {
         "size": 25,
-        "shape": "s",  # square marker
     }
 
     if isinstance(agent, Wolf):
-        portrayal["color"] = WOLF_COLOR
-        portrayal["Layer"] = 3
+        portrayal["color"] = "tab:red"
+        portrayal["marker"] = "o"
+        portrayal["zorder"] = 2
     elif isinstance(agent, Sheep):
-        portrayal["color"] = SHEEP_COLOR
-        portrayal["Layer"] = 2
+        portrayal["color"] = "tab:cyan"
+        portrayal["marker"] = "o"
+        portrayal["zorder"] = 2
     elif isinstance(agent, GrassPatch):
         if agent.fully_grown:
-            portrayal["color"] = "#00FF00"
+            portrayal["color"] = "tab:green"
         else:
-            portrayal["color"] = "#84e184"
-        # portrayal["shape"] = "rect"
-        # portrayal["Filled"] = "true"
-        portrayal["Layer"] = 1
+            portrayal["color"] = "tab:brown"
+        portrayal["marker"] = "s"
+        portrayal["size"] = 75
 
     return portrayal
 
@@ -62,10 +59,20 @@ model_params = {
 }
 
 
-space_component = make_space_matplotlib(wolf_sheep_portrayal)
-lineplot_component = make_plot_measure(["Wolves", "Sheep", "Grass"])
+def post_process(ax):
+    ax.set_aspect("equal")
+    ax.set_xticks([])
+    ax.set_yticks([])
+
+
+space_component = make_space_component(
+    wolf_sheep_portrayal, draw_grid=False, post_process=post_process
+)
+lineplot_component = make_plot_component(
+    {"Wolves": "tab:orange", "Sheep": "tab:cyan", "Grass": "tab:green"}
+)
 
-model = WolfSheep()
+model = WolfSheep(grass=True)
 
 
 page = SolaraViz(

mesa/examples/basic/boid_flockers/app.py

@@ -1,5 +1,5 @@
 from mesa.examples.basic.boid_flockers.model import BoidFlockers
-from mesa.visualization import Slider, SolaraViz, make_space_matplotlib
+from mesa.visualization import Slider, SolaraViz, make_space_component
 
 
 def boid_draw(agent):
@@ -51,7 +51,7 @@ model = BoidFlockers()
 
 page = SolaraViz(
     model,
-    [make_space_matplotlib(agent_portrayal=boid_draw)],
+    [make_space_component(agent_portrayal=boid_draw, backend="matplotlib")],
     model_params=model_params,
     name="Boid Flocking Model",
 )