Mesa 3.0.0b1__py3-none-any.whl → 3.0.0b2__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.0b2"
 __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/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

mesa/examples/advanced/epstein_civil_violence/app.py

@@ -0,0 +1,72 @@
+from mesa.examples.advanced.epstein_civil_violence.agents import Citizen, Cop
+from mesa.examples.advanced.epstein_civil_violence.model import EpsteinCivilViolence
+from mesa.visualization import (
+    Slider,
+    SolaraViz,
+    make_plot_measure,
+    make_space_matplotlib,
+)
+
+COP_COLOR = "#000000"
+AGENT_QUIET_COLOR = "#648FFF"
+AGENT_REBEL_COLOR = "#FE6100"
+JAIL_COLOR = "#808080"
+JAIL_SHAPE = "rect"
+
+
+def citizen_cop_portrayal(agent):
+    if agent is None:
+        return
+
+    portrayal = {
+        "size": 25,
+        "shape": "s",  # square marker
+    }
+
+    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
+
+    elif isinstance(agent, Cop):
+        portrayal["color"] = COP_COLOR
+        portrayal["r"] = 0.9
+        portrayal["layer"] = 1
+
+    return portrayal
+
+
+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_matplotlib(citizen_cop_portrayal)
+chart_component = make_plot_measure(["Quiescent", "Active", "Jailed"])
+
+epstein_model = EpsteinCivilViolence()
+
+page = SolaraViz(
+    epstein_model,
+    components=[space_component, chart_component],
+    model_params=model_params,
+    name="Epstein Civil Violence",
+)
+page  # noqa

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

@@ -1,6 +1,5 @@
 import mesa
-
-from .agent import Citizen, Cop
+from mesa.examples.advanced.epstein_civil_violence.agents import Citizen, Cop
 
 
 class EpsteinCivilViolence(mesa.Model):
@@ -43,8 +42,9 @@ class EpsteinCivilViolence(mesa.Model):
         arrest_prob_constant=2.3,
         movement=True,
         max_iters=1000,
+        seed=None,
     ):
-        super().__init__()
+        super().__init__(seed=seed)
         self.width = width
         self.height = height
         self.citizen_density = citizen_density
@@ -60,7 +60,7 @@ class EpsteinCivilViolence(mesa.Model):
         self.iteration = 0
 
         self.grid = mesa.experimental.cell_space.OrthogonalMooreGrid(
-            (width, height), capacity=1, torus=True
+            (width, height), capacity=1, torus=True, random=self.random
         )
 
         model_reporters = {

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,50 @@
+"""
+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.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",
+        "shape": "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_matplotlib(agent_portrayal=pd_agent_portrayal)
+
+# Create plot for tracking cooperating agents over time
+plot_component = make_plot_measure("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."""

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

@@ -34,51 +34,28 @@ cross over one another otherwise *end*.
 (Epstein and Axtell, 1996, p. 105)
 
 The model demonstrates several Mesa concepts and features:
- - MultiGrid
+ - OrthogonalMooreGrid
  - Multiple agent types (traders, sugar, spice)
  - Dynamically removing agents from the grid and schedule when they die
  - Data Collection at the model and agent level
- - Batchrunner (i.e. parameter sweeps)
+ - custom solara matplotlib space visualization
 
-## 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 a single instance of the model:
-
-```
-  $ python run.py -s
-```
-
-To run the model with BatchRunner:
-
-```
-  $ python run.py -b
-```
-
 To run the model interactively:
 
 ```
-  $ mesa runserver
+  $ solara run app.py
 ```
 
 Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and press Reset, then Run.
 
 ## Files
 
-* `sugarscape_g1mt/trader_agents.py`: Defines the Trader agent class.
-* `sugarscape_g1mt/resource_agents.py`: Defines the Resource agent class which contains an amount of sugar and spice.
-* `sugarscape_g1mt/model.py`: Manages the Sugarscape Constant Growback with Traders model.
-* `sugarscape_g1mt/sugar_map.txt`: Provides sugar and spice landscape in raster type format.
-* `server.py`: Sets up an interactive visualization server.
-* `run.py`: Runs Server, Single Run or Batch Run  with data collection and basic analysis.
+* `model.py`: The Sugarscape Constant Growback with Traders model.
+* `agents.py`: Defines the Trader agent class and the Resource agent class which contains an amount of sugar and spice.
 * `app.py`: Runs a visualization server via Solara (`solara run app.py`).
+* `sugar_map.txt`: Provides sugar and spice landscape in raster type format.
 * `tests.py`: Has tests to ensure that the model reproduces the results in shown in Growing Artificial Societies.
 
 ## Additional Resources

examples/advanced/sugarscape_g1mt/sugarscape_g1mt/trader_agents.py → mesa/examples/advanced/sugarscape_g1mt/agents.py

@@ -1,8 +1,6 @@
 import math
 
-from mesa.experimental.cell_space import CellAgent
-
-from .resource_agents import Resource
+from mesa.experimental.cell_space import CellAgent, FixedAgent
 
 
 # Helper function
@@ -20,6 +18,31 @@ def get_distance(cell_1, cell_2):
     return math.sqrt(dx**2 + dy**2)
 
 
+class Resource(FixedAgent):
+    """
+    Resource:
+    - contains an amount of sugar and spice
+    - grows 1 amount of sugar at each turn
+    - grows 1 amount of spice at each turn
+    """
+
+    def __init__(self, model, max_sugar, max_spice, cell):
+        super().__init__(model)
+        self.sugar_amount = max_sugar
+        self.max_sugar = max_sugar
+        self.spice_amount = max_spice
+        self.max_spice = max_spice
+        self.cell = cell
+
+    def step(self):
+        """
+        Growth function, adds one unit of sugar and spice each step up to
+        max amount
+        """
+        self.sugar_amount = min([self.max_sugar, self.sugar_amount + 1])
+        self.spice_amount = min([self.max_spice, self.spice_amount + 1])
+
+
 class Trader(CellAgent):
     """
     Trader:

{examples → mesa/examples}/advanced/sugarscape_g1mt/app.py

@@ -1,10 +1,19 @@
+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 mesa.visualization import SolaraViz, make_plot_measure
 from sugarscape_g1mt.model import SugarscapeG1mt
 from sugarscape_g1mt.trader_agents import Trader
 
+from mesa.visualization import SolaraViz, make_plot_measure
+
 
 def SpaceDrawer(model):
     def portray(g):
@@ -14,19 +23,19 @@ def SpaceDrawer(model):
             "trader": {"x": [], "y": [], "c": "tab:red", "marker": "o", "s": 10},
         }
 
-        for content, (i, j) in g.coord_iter():
-            for agent in content:
-                if isinstance(agent, Trader):
-                    layers["trader"]["x"].append(i)
-                    layers["trader"]["y"].append(j)
-                else:
-                    # Don't visualize resource with value <= 1.
-                    layers["sugar"][i][j] = (
-                        agent.sugar_amount if agent.sugar_amount > 1 else np.nan
-                    )
-                    layers["spice"][i][j] = (
-                        agent.spice_amount if agent.spice_amount > 1 else np.nan
-                    )
+        for agent in g.all_cells.agents:
+            i, j = agent.cell.coordinate
+            if isinstance(agent, Trader):
+                layers["trader"]["x"].append(i)
+                layers["trader"]["y"].append(j)
+            else:
+                # Don't visualize resource with value <= 1.
+                layers["sugar"][i][j] = (
+                    agent.sugar_amount if agent.sugar_amount > 1 else np.nan
+                )
+                layers["spice"][i][j] = (
+                    agent.spice_amount if agent.spice_amount > 1 else np.nan
+                )
         return layers
 
     fig = Figure()

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

@@ -1,11 +1,10 @@
 from pathlib import Path
 
-import mesa
 import numpy as np
-from mesa.experimental.cell_space import OrthogonalVonNeumannGrid
 
-from .resource_agents import Resource
-from .trader_agents import Trader
+import mesa
+from mesa.examples.advanced.sugarscape_g1mt.agents import Resource, Trader
+from mesa.experimental.cell_space import OrthogonalVonNeumannGrid
 
 
 # Helper Functions
@@ -53,8 +52,9 @@ class SugarscapeG1mt(mesa.Model):
         vision_min=1,
         vision_max=5,
         enable_trade=True,
+        seed=None,
     ):
-        super().__init__()
+        super().__init__(seed=seed)
         # Initiate width and height of sugarscape
         self.width = width
         self.height = height
@@ -176,5 +176,5 @@ class SugarscapeG1mt(mesa.Model):
         self.datacollector._agent_records[self.steps] = agent_trades
 
     def run_model(self, step_count=1000):
-        for i in range(step_count):
+        for _ in range(step_count):
             self.step()

{examples → mesa/examples}/advanced/sugarscape_g1mt/tests.py

@@ -1,11 +1,8 @@
-import random
-
 import numpy as np
 from scipy import stats
-from sugarscape_g1mt.model import SugarscapeG1mt, flatten
-from sugarscape_g1mt.trader_agents import Trader
 
-random.seed(1)
+from .agents import Trader
+from .model import SugarscapeG1mt, flatten
 
 
 def check_slope(y, increasing):
@@ -19,7 +16,7 @@ def check_slope(y, increasing):
 def test_decreasing_price_variance():
     # The variance of the average trade price should decrease over time (figure IV-3)
     # See Growing Artificial Societies p. 109.
-    model = SugarscapeG1mt()
+    model = SugarscapeG1mt(42)
     model.datacollector._new_model_reporter(
         "price_variance",
         lambda m: np.var(

mesa/examples/advanced/wolf_sheep/app.py

@@ -0,0 +1,77 @@
+from mesa.examples.advanced.wolf_sheep.agents import GrassPatch, Sheep, Wolf
+from mesa.examples.advanced.wolf_sheep.model import WolfSheep
+from mesa.visualization import (
+    Slider,
+    SolaraViz,
+    make_plot_measure,
+    make_space_matplotlib,
+)
+
+WOLF_COLOR = "#000000"
+SHEEP_COLOR = "#648FFF"
+
+
+def wolf_sheep_portrayal(agent):
+    if agent is None:
+        return
+
+    portrayal = {
+        "size": 25,
+        "shape": "s",  # square marker
+    }
+
+    if isinstance(agent, Wolf):
+        portrayal["color"] = WOLF_COLOR
+        portrayal["Layer"] = 3
+    elif isinstance(agent, Sheep):
+        portrayal["color"] = SHEEP_COLOR
+        portrayal["Layer"] = 2
+    elif isinstance(agent, GrassPatch):
+        if agent.fully_grown:
+            portrayal["color"] = "#00FF00"
+        else:
+            portrayal["color"] = "#84e184"
+        # portrayal["shape"] = "rect"
+        # portrayal["Filled"] = "true"
+        portrayal["Layer"] = 1
+
+    return portrayal
+
+
+model_params = {
+    # The following line is an example to showcase StaticText.
+    "grass": {
+        "type": "Select",
+        "value": True,
+        "values": [True, False],
+        "label": "grass regrowth enabled?",
+    },
+    "grass_regrowth_time": Slider("Grass Regrowth Time", 20, 1, 50),
+    "initial_sheep": Slider("Initial Sheep Population", 100, 10, 300),
+    "sheep_reproduce": Slider("Sheep Reproduction Rate", 0.04, 0.01, 1.0, 0.01),
+    "initial_wolves": Slider("Initial Wolf Population", 10, 5, 100),
+    "wolf_reproduce": Slider(
+        "Wolf Reproduction Rate",
+        0.05,
+        0.01,
+        1.0,
+        0.01,
+    ),
+    "wolf_gain_from_food": Slider("Wolf Gain From Food Rate", 20, 1, 50),
+    "sheep_gain_from_food": Slider("Sheep Gain From Food", 4, 1, 10),
+}
+
+
+space_component = make_space_matplotlib(wolf_sheep_portrayal)
+lineplot_component = make_plot_measure(["Wolves", "Sheep", "Grass"])
+
+model = WolfSheep()
+
+
+page = SolaraViz(
+    model,
+    components=[space_component, lineplot_component],
+    model_params=model_params,
+    name="Wolf Sheep",
+)
+page  # noqa

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

@@ -10,10 +10,9 @@ Replication of the model found in NetLogo:
 """
 
 import mesa
+from mesa.examples.advanced.wolf_sheep.agents import GrassPatch, Sheep, Wolf
 from mesa.experimental.cell_space import OrthogonalMooreGrid
 
-from .agents import GrassPatch, Sheep, Wolf
-
 
 class WolfSheep(mesa.Model):
     """
@@ -67,7 +66,7 @@ class WolfSheep(mesa.Model):
                                  once it is eaten
             sheep_gain_from_food: Energy sheep gain from grass, if enabled.
         """
-        super().__init__(seed=None)
+        super().__init__(seed=seed)
         # Set parameters
         self.width = width
         self.height = height
@@ -81,15 +80,17 @@ class WolfSheep(mesa.Model):
         collectors = {
             "Wolves": lambda m: len(m.agents_by_type[Wolf]),
             "Sheep": lambda m: len(m.agents_by_type[Sheep]),
+            "Grass": lambda m: len(
+                m.agents_by_type[GrassPatch].select(lambda a: a.fully_grown)
+            )
+            if m.grass
+            else -1,
         }
 
-        if grass:
-            collectors["Grass"] = lambda m: len(m.agents_by_type[GrassPatch])
-
         self.datacollector = mesa.DataCollector(collectors)
 
         # Create sheep:
-        for i in range(self.initial_sheep):
+        for _ in range(self.initial_sheep):
             x = self.random.randrange(self.width)
             y = self.random.randrange(self.height)
             energy = self.random.randrange(2 * self.sheep_gain_from_food)
@@ -132,5 +133,5 @@ class WolfSheep(mesa.Model):
         self.datacollector.collect(self)
 
     def run_model(self, step_count=200):
-        for i in range(step_count):
+        for _ in range(step_count):
             self.step()

mesa/examples/basic/boid_flockers/Readme.md

@@ -0,0 +1,22 @@
+# Boids Flockers
+
+## Summary
+
+An implementation of Craig Reynolds's Boids flocker model. Agents (simulated birds) try to fly towards the average position of their neighbors and in the same direction as them, while maintaining a minimum distance. This produces flocking behavior.
+
+This model tests Mesa's continuous space feature, and uses numpy arrays to represent vectors.
+
+## How to Run
+
+* To launch the visualization interactively, run ``solara run app.py`` in this directory.It will automatically open a browser page.
+
+## Files
+
+* [model.py](model.py): Ccntains the Boid Model
+* [agents.py](agents.py): Contains the Boid agent
+* [app.py](app.py): Solara based Visualization code.
+
+## Further Reading
+
+The following link can be visited for more information on the boid flockers model:
+https://cs.stanford.edu/people/eroberts/courses/soco/projects/2008-09/modeling-natural-systems/boids.html

{examples → mesa/examples}/basic/boid_flockers/app.py

@@ -1,7 +1,6 @@
+from mesa.examples.basic.boid_flockers.model import BoidFlockers
 from mesa.visualization import Slider, SolaraViz, make_space_matplotlib
 
-from .model import BoidFlockers
-
 
 def boid_draw(agent):
     if not agent.neighbors:  # Only for the first Frame