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

mesa/__init__.py

@@ -5,7 +5,6 @@ Core Objects: Model, and Agent.
 
 import datetime
 
-import mesa.examples as examples
 import mesa.experimental as experimental
 import mesa.space as space
 import mesa.time as time
@@ -22,11 +21,10 @@ __all__ = [
     "DataCollector",
     "batch_run",
     "experimental",
-    "examples",
 ]
 
 __title__ = "mesa"
-__version__ = "3.0.0b1"
+__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/agent.py

@@ -21,6 +21,8 @@ from random import Random
 # mypy
 from typing import TYPE_CHECKING, Any, Literal, overload
 
+import numpy as np
+
 if TYPE_CHECKING:
     # We ensure that these are not imported during runtime to prevent cyclic
     # dependency.
@@ -67,7 +69,13 @@ class Agent:
         self.model.register_agent(self)
 
     def remove(self) -> None:
-        """Remove and delete the agent from the model."""
+        """Remove and delete the agent from the model.
+
+        Notes:
+            If you need to do additional cleanup when removing an agent by for example removing
+            it from a space, consider extending this method in your own agent class.
+
+        """
         with contextlib.suppress(KeyError):
             self.model.deregister_agent(self)
 
@@ -79,9 +87,14 @@ class Agent:
 
     @property
     def random(self) -> Random:
-        """Return a seeded rng."""
+        """Return a seeded stdlib rng."""
         return self.model.random
 
+    @property
+    def rng(self) -> np.random.Generator:
+        """Return a seeded np.random rng."""
+        return self.model.rng
+
 
 class AgentSet(MutableSet, Sequence):
     """A collection class that represents an ordered set of agents within an agent-based model (ABM).
@@ -288,15 +301,17 @@ class AgentSet(MutableSet, Sequence):
 
         It's a fast, optimized version of calling shuffle() followed by do().
         """
-        agents = list(self._agents.keys())
-        self.random.shuffle(agents)
+        weakrefs = list(self._agents.keyrefs())
+        self.random.shuffle(weakrefs)
 
         if isinstance(method, str):
-            for agent in agents:
-                getattr(agent, method)(*args, **kwargs)
+            for ref in weakrefs:
+                if (agent := ref()) is not None:
+                    getattr(agent, method)(*args, **kwargs)
         else:
-            for agent in agents:
-                method(agent, *args, **kwargs)
+            for ref in weakrefs:
+                if (agent := ref()) is not None:
+                    method(agent, *args, **kwargs)
 
         return self
 

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

{examples → 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/__init__.py

@@ -0,0 +1,21 @@
+from mesa.examples.advanced.epstein_civil_violence.model import EpsteinCivilViolence
+from mesa.examples.advanced.pd_grid.model import PdGrid
+from mesa.examples.advanced.sugarscape_g1mt.model import SugarscapeG1mt
+from mesa.examples.advanced.wolf_sheep.model import WolfSheep
+from mesa.examples.basic.boid_flockers.model import BoidFlockers
+from mesa.examples.basic.boltzmann_wealth_model.model import BoltzmannWealthModel
+from mesa.examples.basic.conways_game_of_life.model import ConwaysGameOfLife
+from mesa.examples.basic.schelling.model import Schelling
+from mesa.examples.basic.virus_on_network.model import VirusOnNetwork
+
+__all__ = [
+    "BoidFlockers",
+    "BoltzmannWealthModel",
+    "ConwaysGameOfLife",
+    "Schelling",
+    "VirusOnNetwork",
+    "EpsteinCivilViolence",
+    "PdGrid",
+    "SugarscapeG1mt",
+    "WolfSheep",
+]

{examples → mesa/examples}/advanced/epstein_civil_violence/Readme.md

@@ -18,8 +18,9 @@ Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and p
 
 ## Files
 
-* ``EpsteinCivilViolence.py``: Core model and agent code.
-* ``EpsteinCivilViolenceServer.py``: Sets up the interactive visualization.
+* ``model.py``: Core model code.
+* ``agent.py``: Agent classes.
+* ``app.py``: Sets up the interactive visualization.
 * ``Epstein Civil Violence.ipynb``: Jupyter notebook conducting some preliminary analysis of the model.
 
 ## Further Reading

examples/advanced/epstein_civil_violence/epstein_civil_violence/agent.py → 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

@@ -0,0 +1,73 @@
+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_component,
+    make_space_component,
+)
+
+COP_COLOR = "#000000"
+
+agent_colors = {
+    CitizenState.ACTIVE: "#FE6100",
+    CitizenState.QUIET: "#648FFF",
+    CitizenState.ARRESTED: "#808080",
+}
+
+
+def citizen_cop_portrayal(agent):
+    if agent is None:
+        return
+
+    portrayal = {
+        "size": 50,
+    }
+
+    if isinstance(agent, Citizen):
+        portrayal["color"] = agent_colors[agent.state]
+    elif isinstance(agent, Cop):
+        portrayal["color"] = COP_COLOR
+
+    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,
+    "citizen_density": Slider("Initial Agent Density", 0.7, 0.0, 0.9, 0.1),
+    "cop_density": Slider("Initial Cop Density", 0.04, 0.0, 0.1, 0.01),
+    "citizen_vision": Slider("Citizen Vision", 7, 1, 10, 1),
+    "cop_vision": Slider("Cop Vision", 7, 1, 10, 1),
+    "legitimacy": Slider("Government Legitimacy", 0.82, 0.0, 1, 0.01),
+    "max_jail_term": Slider("Max Jail Term", 30, 0, 50, 1),
+}
+
+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()
+
+page = SolaraViz(
+    epstein_model,
+    components=[space_component, chart_component],
+    model_params=model_params,
+    name="Epstein Civil Violence",
+)
+page  # noqa

mesa/examples/advanced/epstein_civil_violence/model.py

@@ -0,0 +1,114 @@
+import mesa
+from mesa.examples.advanced.epstein_civil_violence.agents import (
+    Citizen,
+    CitizenState,
+    Cop,
+)
+
+
+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
+
+    Args:
+        height: grid height
+        width: grid width
+        citizen_density: approximate % of cells occupied by citizens.
+        cop_density: approximate % of cells occupied by cops.
+        citizen_vision: number of cells in each direction (N, S, E and W) that
+            citizen can inspect
+        cop_vision: number of cells in each direction (N, S, E and W) that cop
+            can inspect
+        legitimacy:  (L) citizens' perception of regime legitimacy, equal
+            across all citizens
+        max_jail_term: (J_max)
+        active_threshold: if (grievance - (risk_aversion * arrest_probability))
+            > threshold, citizen rebels
+        arrest_prob_constant: set to ensure agents make plausible arrest
+            probability estimates
+        movement: binary, whether agents try to move at step end
+        max_iters: model may not have a natural stopping point, so we set a
+            max.
+    """
+
+    def __init__(
+        self,
+        width=40,
+        height=40,
+        citizen_density=0.7,
+        cop_density=0.074,
+        citizen_vision=7,
+        cop_vision=7,
+        legitimacy=0.8,
+        max_jail_term=1000,
+        active_threshold=0.1,
+        arrest_prob_constant=2.3,
+        movement=True,
+        max_iters=1000,
+        seed=None,
+    ):
+        super().__init__(seed=seed)
+        self.movement = movement
+        self.max_iters = max_iters
+
+        self.grid = mesa.experimental.cell_space.OrthogonalVonNeumannGrid(
+            (width, height), capacity=1, torus=True, random=self.random
+        )
+
+        model_reporters = {
+            "active": CitizenState.ACTIVE.name,
+            "quiet": CitizenState.QUIET.name,
+            "arrested": CitizenState.ARRESTED.name,
+        }
+        agent_reporters = {
+            "jail_sentence": lambda a: getattr(a, "jail_sentence", None),
+            "arrest_probability": lambda a: getattr(a, "arrest_probability", None),
+        }
+        self.datacollector = mesa.DataCollector(
+            model_reporters=model_reporters, agent_reporters=agent_reporters
+        )
+        if cop_density + citizen_density > 1:
+            raise ValueError("Cop density + citizen density must be less than 1")
+
+        for cell in self.grid.all_cells:
+            klass = self.random.choices(
+                [Citizen, Cop, None],
+                cum_weights=[citizen_density, citizen_density + cop_density, 1],
+            )[0]
+
+            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,
+                    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):
+        """
+        Advance the model by one step and collect data.
+        """
+        self.agents.shuffle_do("step")
+        self._update_counts()
+        self.datacollector.collect(self)
+
+        if self.steps > self.max_iters:
+            self.running = False
+
+    def _update_counts(self):
+        """Helper function for counting nr. of citizens in given state."""
+        counts = self.agents_by_type[Citizen].groupby("state").count()
+
+        for state in CitizenState:
+            setattr(self, state.name, counts.get(state, 0))

examples/advanced/pd_grid/readme.md → mesa/examples/advanced/pd_grid/Readme.md

@@ -19,7 +19,7 @@ The Demographic Prisoner's Dilemma demonstrates how simple rules can lead to the
 
 ##### Web based model simulation
 
-To run the model interactively, run ``mesa runserver`` in this directory.
+To run the model interactively, run ``solara run app.py`` in this directory.
 
 ##### Jupyter Notebook
 
@@ -27,8 +27,9 @@ Launch the ``Demographic Prisoner's Dilemma Activation Schedule.ipynb`` notebook
 
 ## Files
 
-* ``run.py`` is the entry point for the font-end simulations.
-* ``pd_grid/``: contains the model and agent classes; the model takes a ``activation_order`` string as an argument, which determines in which order agents are activated: Sequential, Random or Simultaneous.
+* ``agents.py``: contains the agent class.
+* ``model.py``: contains the model class; the model takes a ``activation_order`` string as an argument, which determines in which order agents are activated: Sequential, Random or Simultaneous.
+* ``app.py``: contains the interactive visualization server.
 * ``Demographic Prisoner's Dilemma Activation Schedule.ipynb``: Jupyter Notebook for running the scheduling experiment. This runs the model three times, one for each activation type, and demonstrates how the activation regime drives the model to different outcomes.
 
 ## Further Reading

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 (
+    SolaraViz,
+    make_plot_component,
+    make_space_component,
+)
+from mesa.visualization.UserParam import Slider
+
+
+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

{examples/advanced/pd_grid → mesa/examples/advanced}/pd_grid/model.py

@@ -1,8 +1,7 @@
 import mesa
+from mesa.examples.advanced.pd_grid.agents import PDAgent
 from mesa.experimental.cell_space import OrthogonalMooreGrid
 
-from .agent import PDAgent
-
 
 class PdGrid(mesa.Model):
     """Model class for iterated, spatial prisoner's dilemma model."""