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

mesa/examples/advanced/wolf_sheep/Readme.md

@@ -14,29 +14,14 @@ The model is tests and demonstrates several Mesa concepts and features:
  - Writing a model composed of multiple files.
  - Dynamically adding and removing agents from the schedule
 
-## Installation
-
-To install the dependencies use pip and the requirements.txt in this directory. e.g.
-
-```
-    # First, we clone the Mesa repo
-    $ git clone https://github.com/projectmesa/mesa.git
-    $ cd mesa
-    # Then we cd to the example directory
-    $ cd examples/wolf_sheep
-    $ pip install -r requirements.txt
-```
-
 ## How to Run
 
-To run the model interactively, run ``mesa runserver`` in this directory. e.g.
+To run the model interactively, in this directory, run the following command
 
 ```
-    $ 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
 
 * ``wolf_sheep/random_walk.py``: This defines the ``RandomWalker`` agent, which implements the behavior of moving randomly across a grid, one cell at a time. Both the Wolf and Sheep agents will inherit from it.

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/Readme.md

@@ -8,7 +8,12 @@ This model tests Mesa's continuous space feature, and uses numpy arrays to repre
 
 ## How to Run
 
-* To launch the visualization interactively, run ``solara run app.py`` in this directory.It will automatically open a browser page.
+To run the model interactively, in this directory, run the following command
+
+```
+    $ solara run app.py
+```
+
 
 ## Files
 

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/Readme.md

@@ -2,25 +2,18 @@
 
 ## Summary
 
-A simple model of agents exchanging wealth. All agents start with the same amount of money. Every step, each agent with one unit of money or more gives one unit of wealth to another random agent. This is the model described in the [Intro Tutorial](https://mesa.readthedocs.io/en/latest/tutorials/intro_tutorial.html), with the completed code.
-
-If you want to go over the step-by-step tutorial, please go and run the [Jupyter Notebook](https://github.com/projectmesa/mesa/blob/main/docs/tutorials/intro_tutorial.ipynb). The code here runs the finalized code in the last cells directly.
+A simple model of agents exchanging wealth. All agents start with the same amount of money. Every step, each agent with one unit of money or more gives one unit of wealth to another random agent. Mesa's [Getting Started](https://mesa.readthedocs.io/latest/getting_started.html) section walks through the Boltzmann Wealth Model in a series of short introductory tutorials, starting with[Creating your First Model](https://mesa.readthedocs.io/latest/tutorials/0_first_model.html).
 
 As the model runs, the distribution of wealth among agents goes from being perfectly uniform (all agents have the same starting wealth), to highly skewed -- a small number have high wealth, more have none at all.
 
 ## How to Run
 
-To follow the tutorial example, launch the Jupyter Notebook and run the code in ``Introduction to Mesa Tutorial Code.ipynb`` which you can find in the main mesa repo [here](https://github.com/projectmesa/mesa/blob/main/docs/tutorials/intro_tutorial.ipynb)
-
-
-To launch the interactive server, as described in the [last section of the tutorial](https://mesa.readthedocs.io/en/latest/tutorials/intro_tutorial.html#adding-visualization), run:
+To run the model interactively, in this directory, run the following command
 
 ```
     $ solara run app.py
 ```
 
-If your browser doesn't open automatically, point it to [http://127.0.0.1:8765/](http://127.0.0.1:8765/). When the visualization loads, click on the Play button.
-
 
 ## Files
 
@@ -46,9 +39,6 @@ Then, you can run the Streamlit app using the following command:
 
 ## Further Reading
 
-The full tutorial describing how the model is built can be found at:
-https://mesa.readthedocs.io/en/latest/tutorials/intro_tutorial.html
-
 This model is drawn from econophysics and presents a statistical mechanics approach to wealth distribution. Some examples of further reading on the topic can be found at:
 
 [Milakovic, M. A Statistical Equilibrium Model of Wealth Distribution. February, 2001.](https://editorialexpress.com/cgi-bin/conference/download.cgi?db_name=SCE2001&paper_id=214)

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/Readme.md

@@ -9,20 +9,12 @@ The "game" is a zero-player game, meaning that its evolution is determined by it
 
 ## How to Run
 
-To run the model interactively you can use either the streamlit or solara version. For solara, you use
+To run the model interactively, in this directory, run the following command
 
 ```
     $ solara run app.py
 ```
 
-For streamlit, you need
-
-```
-    $ streamlit run st_app.py
-```
-
-This will open your browser and show you the controls. You can start the model by hitting the run button.
-
 ## Files
 
 * ``agents.py``: Defines the behavior of an individual cell, which can be in two states: DEAD or ALIVE.

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
 
@@ -14,14 +14,6 @@ To run the model interactively, in this directory, run the following command
     $ solara run app.py
 ```
 
-Then open your browser to [http://127.0.0.1:8765/](http://127.0.0.1:8765/) and click the Play button.
-
-To view and run some example model analyses, launch the IPython Notebook and open ``analysis.ipynb``. Visualizing the analysis also requires [matplotlib](http://matplotlib.org/).
-
-## How to Run without the GUI
-
-To run the model with the grid displayed as an ASCII text, run `python run_ascii.py` in this directory.
-
 ## Files
 
 * ``model.py``: Contains the Schelling model class

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

mesa/examples/basic/virus_on_network/Readme.md

@@ -38,10 +38,6 @@ To run the model interactively, in this directory, run the following command
 
 ## Further Reading
 
-The full tutorial describing how the model is built can be found at:
-https://mesa.readthedocs.io/en/latest/tutorials/intro_tutorial.html
-
-
 [Stonedahl, F. and Wilensky, U. (2008). NetLogo Virus on a Network model](http://ccl.northwestern.edu/netlogo/models/VirusonaNetwork).
 Center for Connected Learning and Computer-Based Modeling, Northwestern University, Evanston, IL.
 

mesa/examples/basic/virus_on_network/app.py

@@ -10,18 +10,19 @@ from mesa.examples.basic.virus_on_network.model import (
 from mesa.visualization import (
     Slider,
     SolaraViz,
+    SpaceRenderer,
     make_plot_component,
-    make_space_component,
 )
+from mesa.visualization.components import AgentPortrayalStyle
 
 
 def agent_portrayal(agent):
     node_color_dict = {
-        State.INFECTED: "tab:red",
-        State.SUSCEPTIBLE: "tab:green",
-        State.RESISTANT: "tab:gray",
+        State.INFECTED: "red",
+        State.SUSCEPTIBLE: "green",
+        State.RESISTANT: "gray",
     }
-    return {"color": node_color_dict[agent.state], "size": 10}
+    return AgentPortrayalStyle(color=node_color_dict[agent.state], size=20)
 
 
 def get_resistant_susceptible_ratio(model):
@@ -92,24 +93,40 @@ model_params = {
 }
 
 
-def post_process_lineplot(ax):
-    ax.set_ylim(ymin=0)
-    ax.set_ylabel("# people")
-    ax.legend(bbox_to_anchor=(1.05, 1.0), loc="upper left")
+def post_process_lineplot(chart):
+    chart = chart.properties(
+        width=400,
+        height=400,
+    ).configure_legend(
+        strokeColor="black",
+        fillColor="#ECE9E9",
+        orient="right",
+        cornerRadius=5,
+        padding=10,
+        strokeWidth=1,
+    )
+    return chart
+
 
+model1 = VirusOnNetwork()
+renderer = SpaceRenderer(model1, backend="altair")
+renderer.draw_structure(
+    node_kwargs={"color": "black", "filled": False, "strokeWidth": 5},
+    edge_kwargs={"strokeDash": [6, 1]},
+)  # Do this to draw the underlying network and customize it
+renderer.draw_agents(agent_portrayal)
 
-SpacePlot = make_space_component(agent_portrayal)
+# Plot components can also be in altair and support post_process
 StatePlot = make_plot_component(
-    {"Infected": "tab:red", "Susceptible": "tab:green", "Resistant": "tab:gray"},
+    {"Infected": "red", "Susceptible": "green", "Resistant": "gray"},
+    backend="altair",
     post_process=post_process_lineplot,
 )
 
-model1 = VirusOnNetwork()
-
 page = SolaraViz(
     model1,
+    renderer,
     components=[
-        SpacePlot,
         StatePlot,
         get_resistant_susceptible_ratio,
     ],

mesa/experimental/__init__.py

@@ -15,6 +15,6 @@ Notes:
     - Features graduate from experimental status once their APIs are stabilized
 """
 
-from mesa.experimental import continuous_space, devs, mesa_signals
+from mesa.experimental import continuous_space, devs, mesa_signals, meta_agents
 
-__all__ = ["continuous_space", "devs", "mesa_signals"]
+__all__ = ["continuous_space", "devs", "mesa_signals", "meta_agents"]