Mesa 3.2.0__py3-none-any.whl → 3.3.0__py3-none-any.whl

mesa/__init__.py

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

mesa/agent.py

@@ -185,7 +185,7 @@ class AgentSet(MutableSet, Sequence):
                 Random()
             )  # FIXME see issue 1981, how to get the central rng from model
         self.random = random
-        self._agents = weakref.WeakKeyDictionary({agent: None for agent in agents})
+        self._agents = weakref.WeakKeyDictionary(dict.fromkeys(agents))
 
     def __len__(self) -> int:
         """Return the number of agents in the AgentSet."""
@@ -264,7 +264,7 @@ class AgentSet(MutableSet, Sequence):
         self.random.shuffle(weakrefs)
 
         if inplace:
-            self._agents.data = {entry: None for entry in weakrefs}
+            self._agents.data = dict.fromkeys(weakrefs)
             return self
         else:
             return AgentSet(
@@ -303,7 +303,7 @@ class AgentSet(MutableSet, Sequence):
 
         This is a private method primarily used internally by other methods like select, shuffle, and sort.
         """
-        self._agents = weakref.WeakKeyDictionary({agent: None for agent in agents})
+        self._agents = weakref.WeakKeyDictionary(dict.fromkeys(agents))
         return self
 
     def do(self, method: str | Callable, *args, **kwargs) -> AgentSet:

mesa/datacollection.py

@@ -300,7 +300,7 @@ class DataCollector:
         if agent_type in agent_types:
             agents = model.agents_by_type[agent_type]
         else:
-            from mesa import Agent
+            from mesa import Agent  # noqa: PLC0415
 
             if issubclass(agent_type, Agent):
                 agents = [

mesa/examples/advanced/epstein_civil_violence/app.py

@@ -7,9 +7,10 @@ from mesa.examples.advanced.epstein_civil_violence.model import EpsteinCivilViol
 from mesa.visualization import (
     Slider,
     SolaraViz,
+    SpaceRenderer,
     make_plot_component,
-    make_space_component,
 )
+from mesa.visualization.components import AgentPortrayalStyle
 
 COP_COLOR = "#000000"
 
@@ -24,14 +25,12 @@ def citizen_cop_portrayal(agent):
     if agent is None:
         return
 
-    portrayal = {
-        "size": 50,
-    }
+    portrayal = AgentPortrayalStyle(size=200)
 
     if isinstance(agent, Citizen):
-        portrayal["color"] = agent_colors[agent.state]
+        portrayal.update(("color", agent_colors[agent.state]))
     elif isinstance(agent, Cop):
-        portrayal["color"] = COP_COLOR
+        portrayal.update(("color", COP_COLOR))
 
     return portrayal
 
@@ -51,7 +50,7 @@ model_params = {
     },
     "height": 40,
     "width": 40,
-    "citizen_density": Slider("Initial Agent Density", 0.7, 0.0, 0.9, 0.1),
+    "citizen_density": Slider("Initial Agent Density", 0.7, 0.1, 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),
@@ -59,19 +58,20 @@ model_params = {
     "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()
+renderer = SpaceRenderer(epstein_model, backend="matplotlib")
+renderer.draw_agents(citizen_cop_portrayal)
+renderer.post_process = post_process
 
 page = SolaraViz(
     epstein_model,
-    components=[space_component, chart_component],
+    renderer,
+    components=[chart_component],
     model_params=model_params,
     name="Epstein Civil Violence",
 )

mesa/examples/advanced/pd_grid/app.py

@@ -6,20 +6,19 @@ from mesa.examples.advanced.pd_grid.model import PdGrid
 from mesa.visualization import (
     Slider,
     SolaraViz,
+    SpaceRenderer,
     make_plot_component,
-    make_space_component,
 )
+from mesa.visualization.components import AgentPortrayalStyle
 
 
 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,
-    }
+    return AgentPortrayalStyle(
+        color="blue" if agent.move == "C" else "red", marker="s", size=25
+    )
 
 
 # Model parameters
@@ -40,19 +39,19 @@ model_params = {
 }
 
 
-# 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")
+plot_component = make_plot_component("Cooperating_Agents", backend="altair", grid=True)
 
 # Initialize model
 initial_model = PdGrid()
+# Create grid and agent visualization component using Altair
+renderer = SpaceRenderer(initial_model, backend="altair").render(pd_agent_portrayal)
 
 # Create visualization with all components
 page = SolaraViz(
     model=initial_model,
-    components=[grid_viz, plot_component],
+    renderer=renderer,
+    components=[plot_component],
     model_params=model_params,
     name="Spatial Prisoner's Dilemma",
 )

mesa/examples/advanced/sugarscape_g1mt/app.py

@@ -1,24 +1,31 @@
 from mesa.examples.advanced.sugarscape_g1mt.model import SugarscapeG1mt
-from mesa.visualization import Slider, SolaraViz, make_plot_component
-from mesa.visualization.components.matplotlib_components import make_mpl_space_component
+from mesa.visualization import Slider, SolaraViz, SpaceRenderer, make_plot_component
+from mesa.visualization.components import AgentPortrayalStyle, PropertyLayerStyle
 
 
 def agent_portrayal(agent):
-    return {"marker": "o", "color": "red", "size": 10}
+    return AgentPortrayalStyle(
+        x=agent.cell.coordinate[0],
+        y=agent.cell.coordinate[1],
+        color="red",
+        marker="o",
+        size=10,
+        zorder=1,
+    )
 
 
-propertylayer_portrayal = {
-    "sugar": {"color": "blue", "alpha": 0.8, "colorbar": True, "vmin": 0, "vmax": 10},
-    "spice": {"color": "red", "alpha": 0.8, "colorbar": True, "vmin": 0, "vmax": 10},
-}
+def propertylayer_portrayal(layer):
+    if layer.name == "sugar":
+        return PropertyLayerStyle(
+            color="blue", alpha=0.8, colorbar=True, vmin=0, vmax=10
+        )
+    return PropertyLayerStyle(color="red", alpha=0.8, colorbar=True, vmin=0, vmax=10)
 
 
-sugarscape_space = make_mpl_space_component(
-    agent_portrayal=agent_portrayal,
-    propertylayer_portrayal=propertylayer_portrayal,
-    post_process=None,
-    draw_grid=False,
-)
+def post_process(chart):
+    chart = chart.properties(width=400, height=400)
+    return chart
+
 
 model_params = {
     "seed": {
@@ -47,12 +54,23 @@ model_params = {
 
 model = SugarscapeG1mt()
 
+# Here, the renderer uses the Altair backend, while the plot components
+# use the Matplotlib backend.
+# Both can be mixed and matched to enhance the visuals of your model.
+renderer = SpaceRenderer(model, backend="altair").render(
+    agent_portrayal=agent_portrayal,
+    propertylayer_portrayal=propertylayer_portrayal,
+    post_process=post_process,
+)
+
+# Note: It is advised to switch the pages after pausing the model
+# on the Solara dashboard.
 page = SolaraViz(
     model,
+    renderer,
     components=[
-        sugarscape_space,
-        make_plot_component("#Traders"),
-        make_plot_component("Price"),
+        make_plot_component("#Traders", page=1),
+        make_plot_component("Price", page=1),
     ],
     model_params=model_params,
     name="Sugarscape {G1, M, T}",

mesa/examples/advanced/wolf_sheep/app.py

@@ -5,34 +5,32 @@ from mesa.visualization import (
     CommandConsole,
     Slider,
     SolaraViz,
+    SpaceRenderer,
     make_plot_component,
-    make_space_component,
 )
+from mesa.visualization.components import AgentPortrayalStyle
 
 
 def wolf_sheep_portrayal(agent):
     if agent is None:
         return
 
-    portrayal = {
-        "size": 25,
-    }
+    portrayal = AgentPortrayalStyle(
+        size=50,
+        marker="o",
+        zorder=2,
+    )
 
     if isinstance(agent, Wolf):
-        portrayal["color"] = "tab:red"
-        portrayal["marker"] = "o"
-        portrayal["zorder"] = 2
+        portrayal.update(("color", "red"))
     elif isinstance(agent, Sheep):
-        portrayal["color"] = "tab:cyan"
-        portrayal["marker"] = "o"
-        portrayal["zorder"] = 2
+        portrayal.update(("color", "cyan"))
     elif isinstance(agent, GrassPatch):
         if agent.fully_grown:
-            portrayal["color"] = "tab:green"
+            portrayal.update(("color", "tab:green"))
         else:
-            portrayal["color"] = "tab:brown"
-        portrayal["marker"] = "s"
-        portrayal["size"] = 75
+            portrayal.update(("color", "tab:brown"))
+        portrayal.update(("marker", "s"), ("size", 125), ("zorder", 1))
 
     return portrayal
 
@@ -75,9 +73,6 @@ def post_process_lines(ax):
     ax.legend(loc="center left", bbox_to_anchor=(1, 0.9))
 
 
-space_component = make_space_component(
-    wolf_sheep_portrayal, draw_grid=False, post_process=post_process_space
-)
 lineplot_component = make_plot_component(
     {"Wolves": "tab:orange", "Sheep": "tab:cyan", "Grass": "tab:green"},
     post_process=post_process_lines,
@@ -86,9 +81,17 @@ lineplot_component = make_plot_component(
 simulator = ABMSimulator()
 model = WolfSheep(simulator=simulator, grass=True)
 
+renderer = SpaceRenderer(
+    model,
+    backend="matplotlib",
+)
+renderer.draw_agents(wolf_sheep_portrayal)
+renderer.post_process = post_process_space
+
 page = SolaraViz(
     model,
-    components=[space_component, lineplot_component, CommandConsole],
+    renderer,
+    components=[lineplot_component, CommandConsole],
     model_params=model_params,
     name="Wolf Sheep",
     simulator=simulator,

mesa/examples/basic/boid_flockers/app.py

@@ -1,12 +1,8 @@
-import os
-import sys
-
 from matplotlib.markers import MarkerStyle
 
-sys.path.insert(0, os.path.abspath("../../../.."))
-
 from mesa.examples.basic.boid_flockers.model import BoidFlockers
-from mesa.visualization import Slider, SolaraViz, make_space_component
+from mesa.visualization import Slider, SolaraViz, SpaceRenderer
+from mesa.visualization.components import AgentPortrayalStyle
 
 # Pre-compute markers for different angles (e.g., every 10 degrees)
 MARKER_CACHE = {}
@@ -25,10 +21,12 @@ def boid_draw(agent):
     rounded_deg = round(deg / 10) * 10 % 360
 
     # using cached markers to speed things up
-    if neighbors <= 1:
-        return {"color": "red", "size": 20, "marker": MARKER_CACHE[rounded_deg]}
-    elif neighbors >= 2:
-        return {"color": "green", "size": 20, "marker": MARKER_CACHE[rounded_deg]}
+    boid_style = AgentPortrayalStyle(
+        color="red", size=20, marker=MARKER_CACHE[rounded_deg]
+    )
+    if neighbors >= 2:
+        boid_style.update(("color", "green"), ("marker", MARKER_CACHE[rounded_deg]))
+    return boid_style
 
 
 model_params = {
@@ -71,9 +69,15 @@ model_params = {
 
 model = BoidFlockers()
 
+# Quickest way to visualize grid along with agents or property layers.
+renderer = SpaceRenderer(
+    model,
+    backend="matplotlib",
+).render(agent_portrayal=boid_draw)
+
 page = SolaraViz(
     model,
-    components=[make_space_component(agent_portrayal=boid_draw, backend="matplotlib")],
+    renderer,
     model_params=model_params,
     name="Boid Flocking Model",
 )

mesa/examples/basic/boltzmann_wealth_model/app.py

@@ -1,17 +1,21 @@
+import altair as alt
+
 from mesa.examples.basic.boltzmann_wealth_model.model import BoltzmannWealth
 from mesa.mesa_logging import INFO, log_to_stderr
 from mesa.visualization import (
     SolaraViz,
+    SpaceRenderer,
     make_plot_component,
-    make_space_component,
 )
+from mesa.visualization.components import AgentPortrayalStyle
 
 log_to_stderr(INFO)
 
 
 def agent_portrayal(agent):
-    color = agent.wealth  # we are using a colormap to translate wealth to color
-    return {"color": color}
+    return AgentPortrayalStyle(
+        color=agent.wealth
+    )  # we are using a colormap to translate wealth to color
 
 
 model_params = {
@@ -33,45 +37,48 @@ model_params = {
 }
 
 
-def post_process(ax):
-    ax.get_figure().colorbar(ax.collections[0], label="wealth", ax=ax)
+def post_process(chart):
+    """Post-process the Altair chart to add a colorbar legend."""
+    chart = chart.encode(
+        color=alt.Color(
+            "color:N",
+            scale=alt.Scale(scheme="viridis", domain=[0, 10]),
+            legend=alt.Legend(
+                title="Wealth",
+                orient="right",
+                type="gradient",
+                gradientLength=200,
+            ),
+        ),
+    )
+    return chart
 
 
-# Create initial model instance
 model = BoltzmannWealth(50, 10, 10)
 
-# Create visualization elements. The visualization elements are solara components
-# that receive the model instance as a "prop" and display it in a certain way.
-# Under the hood these are just classes that receive the model instance.
-# You can also author your own visualization elements, which can also be functions
-# that receive the model instance and return a valid solara component.
+# The SpaceRenderer is responsible for drawing the model's space and agents.
+# It builds the visualization in layers, first drawing the grid structure,
+# and then drawing the agents on top. It uses a specified backend
+# (like "altair" or "matplotlib") for creating the plots.
+renderer = SpaceRenderer(model, backend="altair")
+# Can customize the grid appearance.
+renderer.draw_structure(grid_color="black", grid_dash=[6, 2], grid_opacity=0.3)
+renderer.draw_agents(agent_portrayal=agent_portrayal, cmap="viridis", vmin=0, vmax=10)
 
-SpaceGraph = make_space_component(
-    agent_portrayal, cmap="viridis", vmin=0, vmax=10, post_process=post_process
-)
+# The post_process function is used to modify the Altair chart after it has been created.
+# It can be used to add legends, colorbars, or other visual elements.
+renderer.post_process = post_process
+
+# Creates a line plot component from the model's "Gini" datacollector.
 GiniPlot = make_plot_component("Gini")
 
-# Create the SolaraViz page. This will automatically create a server and display the
-# visualization elements in a web browser.
-# Display it using the following command in the example directory:
-# solara run app.py
-# It will automatically update and display any changes made to this file
+# The SolaraViz page combines the model, renderer, and components into a web interface.
+# To run the visualization, save this code as app.py and run `solara run app.py`
 page = SolaraViz(
     model,
-    components=[SpaceGraph, GiniPlot],
+    renderer,
+    components=[GiniPlot],
     model_params=model_params,
     name="Boltzmann Wealth Model",
 )
 page  # noqa
-
-
-# In a notebook environment, we can also display the visualization elements directly
-# SpaceGraph(model1)
-# GiniPlot(model1)
-
-# The plots will be static. If you want to pick up model steps,
-# you have to make the model reactive first
-# reactive_model = solara.reactive(model1)
-# SpaceGraph(reactive_model)
-# In a different notebook block:
-# reactive_model.value.step()

mesa/examples/basic/conways_game_of_life/app.py

@@ -1,16 +1,17 @@
 from mesa.examples.basic.conways_game_of_life.model import ConwaysGameOfLife
 from mesa.visualization import (
     SolaraViz,
-    make_space_component,
+    SpaceRenderer,
 )
+from mesa.visualization.components import AgentPortrayalStyle
 
 
 def agent_portrayal(agent):
-    return {
-        "color": "white" if agent.state == 0 else "black",
-        "marker": "s",
-        "size": 25,
-    }
+    return AgentPortrayalStyle(
+        color="white" if agent.state == 0 else "black",
+        marker="s",
+        size=30,
+    )
 
 
 def post_process(ax):
@@ -54,15 +55,11 @@ model_params = {
 # Create initial model instance
 model1 = ConwaysGameOfLife()
 
-# Create visualization elements. The visualization elements are solara components
-# that receive the model instance as a "prop" and display it in a certain way.
-# Under the hood these are just classes that receive the model instance.
-# You can also author your own visualization elements, which can also be functions
-# that receive the model instance and return a valid solara component.
-SpaceGraph = make_space_component(
-    agent_portrayal, post_process=post_process, draw_grid=False
-)
-
+renderer = SpaceRenderer(model1, backend="matplotlib")
+# In this case the renderer only draws the agents because we just want to observe
+# the state of the agents, not the structure of the grid.
+renderer.draw_agents(agent_portrayal=agent_portrayal)
+renderer.post_process = post_process
 
 # Create the SolaraViz page. This will automatically create a server and display the
 # visualization elements in a web browser.
@@ -71,7 +68,7 @@ SpaceGraph = make_space_component(
 # It will automatically update and display any changes made to this file
 page = SolaraViz(
     model1,
-    components=[SpaceGraph],
+    renderer,
     model_params=model_params,
     name="Game of Life",
 )

mesa/examples/basic/schelling/Readme.md

@@ -2,9 +2,9 @@
 
 ## Summary
 
-The Schelling segregation model is a classic agent-based model, demonstrating how even a mild preference for similar neighbors can lead to a much higher degree of segregation than we would intuitively expect. The model consists of agents on a square grid, where each grid cell can contain at most one agent. Agents come in two colors: red and blue. They are happy if a certain number of their eight possible neighbors are of the same color, and unhappy otherwise. Unhappy agents will pick a random empty cell to move to each step, until they are happy. The model keeps running until there are no unhappy agents.
+The Schelling segregation model is a classic agent-based model, demonstrating how even a mild preference for similar neighbors can lead to a much higher degree of segregation than we would intuitively expect. The model consists of agents on a square grid, where each grid cell can contain at most one agent. Agents come in two colors: orange and blue. They are happy if a certain number of their eight possible neighbors are of the same color, and unhappy otherwise. Unhappy agents will pick a random empty cell to move to each step, until they are happy. The model keeps running until there are no unhappy agents.
 
-By default, the number of similar neighbors the agents need to be happy is set to 3. That means the agents would be perfectly happy with a majority of their neighbors being of a different color (e.g. a Blue agent would be happy with five Red neighbors and three Blue ones). Despite this, the model consistently leads to a high degree of segregation, with most agents ending up with no neighbors of a different color.
+By default, the number of similar neighbors the agents need to be happy is set to 3. That means the agents would be perfectly happy with a majority of their neighbors being of a different color (e.g. a Blue agent would be happy with five Orange neighbors and three Blue ones). Despite this, the model consistently leads to a high degree of segregation, with most agents ending up with no neighbors of a different color.
 
 ## How to Run
 

mesa/examples/basic/schelling/agents.py

@@ -19,8 +19,9 @@ class SchellingAgent(CellAgent):
         self.type = agent_type
         self.homophily = homophily
         self.radius = radius
+        self.happy = False
 
-    def step(self) -> None:
+    def assign_state(self) -> None:
         """Determine if agent is happy and move if necessary."""
         neighbors = list(self.cell.get_neighborhood(radius=self.radius).agents)
 
@@ -34,8 +35,13 @@ class SchellingAgent(CellAgent):
             # If there are no neighbors, the similarity fraction is 0
             similarity_fraction = 0.0
 
-        # Move if unhappy
         if similarity_fraction < self.homophily:
-            self.cell = self.model.grid.select_random_empty_cell()
+            self.happy = False
         else:
+            self.happy = True
             self.model.happy += 1
+
+    def step(self) -> None:
+        # Move if unhappy
+        if not self.happy:
+            self.cell = self.model.grid.select_random_empty_cell()

mesa/examples/basic/schelling/app.py

@@ -1,12 +1,15 @@
+import os
+
 import solara
 
 from mesa.examples.basic.schelling.model import Schelling
 from mesa.visualization import (
     Slider,
     SolaraViz,
+    SpaceRenderer,
     make_plot_component,
-    make_space_component,
 )
+from mesa.visualization.components import AgentPortrayalStyle
 
 
 def get_happy_agents(model):
@@ -14,8 +17,45 @@ def get_happy_agents(model):
     return solara.Markdown(f"**Happy agents: {model.happy}**")
 
 
+path = os.path.dirname(os.path.abspath(__file__))
+
+
 def agent_portrayal(agent):
-    return {"color": "tab:orange" if agent.type == 0 else "tab:blue"}
+    style = AgentPortrayalStyle(
+        x=agent.cell.coordinate[0],
+        y=agent.cell.coordinate[1],
+        marker=os.path.join(path, "resources", "orange_happy.png"),
+        size=75,
+    )
+    if agent.type == 0:
+        if agent.happy:
+            style.update(
+                (
+                    "marker",
+                    os.path.join(path, "resources", "blue_happy.png"),
+                ),
+            )
+        else:
+            style.update(
+                (
+                    "marker",
+                    os.path.join(path, "resources", "blue_unhappy.png"),
+                ),
+                ("size", 50),
+                ("zorder", 2),
+            )
+    else:
+        if not agent.happy:
+            style.update(
+                (
+                    "marker",
+                    os.path.join(path, "resources", "orange_unhappy.png"),
+                ),
+                ("size", 50),
+                ("zorder", 2),
+            )
+
+    return style
 
 
 model_params = {
@@ -31,14 +71,21 @@ model_params = {
     "height": 20,
 }
 
+# Note: Models with images as markers are very performance intensive.
 model1 = Schelling()
+renderer = SpaceRenderer(model1, backend="matplotlib")
+# Here we use renderer.render() to render the agents and grid in one go.
+# This function always renders the grid and then renders the agents or
+# property layers on top of it if specified. It also supports passing the
+# post_process function to fine-tune the plot after rendering in itself.
+renderer.render(agent_portrayal=agent_portrayal)
 
 HappyPlot = make_plot_component({"happy": "tab:green"})
 
 page = SolaraViz(
     model1,
+    renderer,
     components=[
-        make_space_component(agent_portrayal),
         HappyPlot,
         get_happy_agents,
     ],

mesa/examples/basic/schelling/model.py

@@ -68,11 +68,13 @@ class Schelling(Model):
                 )
 
         # Collect initial state
+        self.agents.do("assign_state")
         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")  # Activate all agents in random order
+        self.agents.do("assign_state")
         self.datacollector.collect(self)  # Collect data
         self.running = self.happy < len(self.agents)  # Continue until everyone is happy