Mesa 3.2.0.dev0__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.dev"
+__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

@@ -53,13 +53,12 @@ class Agent:
 
         Args:
             model (Model): The model instance in which the agent exists.
-            args: passed on to super
-            kwargs: passed on to super
+            args: Passed on to super.
+            kwargs: Passed on to super.
 
         Notes:
             to make proper use of python's super, in each class remove the arguments and
             keyword arguments you need and pass on the rest to super
-
         """
         super().__init__(*args, **kwargs)
 
@@ -103,7 +102,10 @@ class Agent:
         """
 
         class ListLike:
-            """Helper class to make default arguments act as if they are in a list of length N."""
+            """Make default arguments act as if they are in a list of length N.
+
+            This is a helper class.
+            """
 
             def __init__(self, value):
                 self.value = value
@@ -183,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."""
@@ -262,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(
@@ -301,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/README.md

@@ -12,7 +12,7 @@ The examples are categorized into two groups:
 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](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.
+Completed code to go along with the [tutorial](https://mesa.readthedocs.io/latest/tutorials/0_first_model.html) on making a simple model of how a highly-skewed wealth distribution can emerge from simple rules.
 
 ### [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.

mesa/examples/__init__.py

@@ -1,3 +1,4 @@
+from mesa.examples.advanced.alliance_formation.model import MultiLevelAllianceModel
 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
@@ -13,6 +14,7 @@ __all__ = [
     "BoltzmannWealth",
     "ConwaysGameOfLife",
     "EpsteinCivilViolence",
+    "MultiLevelAllianceModel",
     "PdGrid",
     "Schelling",
     "SugarscapeG1mt",

mesa/examples/advanced/alliance_formation/Readme.md

@@ -0,0 +1,50 @@
+# Alliance Formation Model (Meta-Agent Example)
+
+## Summary
+
+This model demonstrates Mesa's meta agent capability.
+
+**Overview of meta agent:** Complex systems often have multiple levels of components. A city is not a single entity, but it is made of districts,neighborhoods, buildings, and people. A forest comprises an ecosystem of trees, plants, animals, and microorganisms. An organization is not one entity, but is made of departments, sub-departments, and people. A person is not a single entity, but it is made of micro biomes, organs and cells.
+
+This reality is the motivation for meta-agents. It allows users to represent these multiple levels, where each level can have agents with sub-agents.
+
+This model demonstrates Mesa's ability to dynamically create new classes of agents that are composed of existing agents. These meta-agents inherits functions and attributes from their sub-agents and users can specify new functionality or attributes they want the meta agent to have. For example, if a user is doing a factory simulation with autonomous systems, each major component of that system can be a sub-agent of the overall robot agent. Or, if someone is doing a simulation of an organization, individuals can be part of different organizational units that are working for some purpose.
+
+To provide a simple demonstration of this capability is an alliance formation model.
+
+In this simulation n agents are created, who have two attributes (1) power and (2) preference. Each attribute is a number between 0 and 1 over a gaussian distribution. Agents then randomly select other agents and use the [bilateral shapley value](https://en.wikipedia.org/wiki/Shapley_value) to determine if they should form an alliance. If the expected utility support an alliances, the agent creates a meta-agent. Subsequent steps may add agents to the meta-agent, create new instances of similar hierarchy, or create a new hierarchy level where meta-agents form an alliance of meta-agents. In this visualization of this model a new meta-agent hierarchy will be a larger node and a new color.
+
+In MetaAgents current configuration, agents being part of multiple meta-agents is not supported.
+
+If you would like to see an example of explicit meta-agent formation see the [warehouse model in the Mesa example's repository](https://github.com/projectmesa/mesa-examples/tree/main/examples/warehouse)
+
+
+## Installation
+
+This model requires Mesa's recommended install and scipy
+
+```
+    $ pip install mesa[rec]
+```
+
+## How to Run
+
+To run the model interactively, in this directory, run the following command
+
+```
+    $ solara run app.py
+```
+
+## Files
+
+- `model.py`: Contains creation of agents, the network and management of agent execution.
+- `agents.py`: Contains logic for forming alliances and creation of new agents
+- `app.py`: Contains the code for the interactive Solara visualization.
+
+## 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
+
+An example of the bilateral shapley value in another model:
+[Techno-Social Energy Infrastructure Siting: Sustainable Energy Modeling Programming (SEMPro)](https://www.jasss.org/16/3/6.html)

mesa/examples/advanced/alliance_formation/agents.py

@@ -0,0 +1,20 @@
+import mesa
+
+
+class AllianceAgent(mesa.Agent):
+    """
+    Agent has three attributes power (float), position (float) and level (int)
+
+    """
+
+    def __init__(self, model, power, position, level=0):
+        super().__init__(model)
+        self.power = power
+        self.position = position
+        self.level = level
+
+    """
+    For this demo model agent only need attributes.
+
+    More complex models could have functions that define agent behavior.
+    """

mesa/examples/advanced/alliance_formation/app.py

@@ -0,0 +1,71 @@
+import matplotlib.pyplot as plt
+import networkx as nx
+import solara
+from matplotlib.figure import Figure
+
+from mesa.examples.advanced.alliance_formation.model import MultiLevelAllianceModel
+from mesa.visualization import SolaraViz
+from mesa.visualization.utils import update_counter
+
+model_params = {
+    "seed": {
+        "type": "InputText",
+        "value": 42,
+        "label": "Random Seed",
+    },
+    "n": {
+        "type": "SliderInt",
+        "value": 50,
+        "label": "Number of agents:",
+        "min": 10,
+        "max": 100,
+        "step": 1,
+    },
+}
+
+# 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.
+
+
+@solara.component
+def plot_network(model):
+    update_counter.get()
+    g = model.network
+    pos = nx.fruchterman_reingold_layout(g)
+    fig = Figure()
+    ax = fig.subplots()
+    labels = {agent.unique_id: agent.unique_id for agent in model.agents}
+    node_sizes = [g.nodes[node]["size"] for node in g.nodes]
+    node_colors = [g.nodes[node]["size"] for node in g.nodes()]
+
+    nx.draw(
+        g,
+        pos,
+        node_size=node_sizes,
+        node_color=node_colors,
+        cmap=plt.cm.coolwarm,
+        labels=labels,
+        ax=ax,
+    )
+
+    solara.FigureMatplotlib(fig)
+
+
+# Create initial model instance
+model = MultiLevelAllianceModel(50)
+
+# 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
+page = SolaraViz(
+    model,
+    components=[plot_network],
+    model_params=model_params,
+    name="Alliance Formation Model",
+)
+page  # noqa

mesa/examples/advanced/alliance_formation/model.py

@@ -0,0 +1,184 @@
+import networkx as nx
+import numpy as np
+
+import mesa
+from mesa import Agent
+from mesa.examples.advanced.alliance_formation.agents import AllianceAgent
+from mesa.experimental.meta_agents.meta_agent import (
+    create_meta_agent,
+    find_combinations,
+)
+
+
+class MultiLevelAllianceModel(mesa.Model):
+    """
+    Model for simulating multi-level alliances among agents.
+    """
+
+    def __init__(self, n=50, mean=0.5, std_dev=0.1, seed=42):
+        """
+        Initialize the model.
+
+        Args:
+            n (int): Number of agents.
+            mean (float): Mean value for normal distribution.
+            std_dev (float): Standard deviation for normal distribution.
+            seed (int): Random seed.
+        """
+        super().__init__(seed=seed)
+        self.population = n
+        self.network = nx.Graph()  # Initialize the network
+        self.datacollector = mesa.DataCollector(model_reporters={"Network": "network"})
+
+        # Create Agents
+        power = self.rng.normal(mean, std_dev, n)
+        power = np.clip(power, 0, 1)
+        position = self.rng.normal(mean, std_dev, n)
+        position = np.clip(position, 0, 1)
+        AllianceAgent.create_agents(self, n, power, position)
+        agent_ids = [
+            (agent.unique_id, {"size": 300, "level": 0}) for agent in self.agents
+        ]
+        self.network.add_nodes_from(agent_ids)
+
+    def add_link(self, meta_agent, agents):
+        """
+        Add links between a meta agent and its constituent agents in the network.
+
+        Args:
+            meta_agent (MetaAgent): The meta agent.
+            agents (list): List of agents.
+        """
+        for agent in agents:
+            self.network.add_edge(meta_agent.unique_id, agent.unique_id)
+
+    def calculate_shapley_value(self, agents):
+        """
+        Calculate the Shapley value of the two agents.
+
+        Args:
+            agents (list): List of agents.
+
+        Returns:
+            tuple: Potential utility, new position, and level.
+        """
+        positions = agents.get("position")
+        new_position = 1 - (max(positions) - min(positions))
+        potential_utility = agents.agg("power", sum) * 1.2 * new_position
+
+        value_0 = 0.5 * agents[0].power + 0.5 * (potential_utility - agents[1].power)
+        value_1 = 0.5 * agents[1].power + 0.5 * (potential_utility - agents[0].power)
+
+        if value_0 > agents[0].power and value_1 > agents[1].power:
+            if agents[0].level > agents[1].level:
+                level = agents[0].level
+            elif agents[0].level == agents[1].level:
+                level = agents[0].level + 1
+            else:
+                level = agents[1].level
+
+            return potential_utility, new_position, level
+
+    def only_best_combination(self, combinations):
+        """
+        Filter to keep only the best combination for each agent.
+
+        Args:
+            combinations (list): List of combinations.
+
+        Returns:
+            dict: Unique combinations.
+        """
+        best = {}
+        # Determine best option for EACH agent
+        for group, value in combinations:
+            agent_ids = sorted(group.get("unique_id"))  # by default is bilateral
+            # Deal with all possibilities
+            if (
+                agent_ids[0] not in best and agent_ids[1] not in best
+            ):  # if neither in add both
+                best[agent_ids[0]] = [group, value, agent_ids]
+                best[agent_ids[1]] = [group, value, agent_ids]
+            elif (
+                agent_ids[0] in best and agent_ids[1] in best
+            ):  # if both in, see if both would be trading up
+                if (
+                    value[0] > best[agent_ids[0]][1][0]
+                    and value[0] > best[agent_ids[1]][1][0]
+                ):
+                    # Remove the old alliances
+                    del best[best[agent_ids[0]][2][1]]
+                    del best[best[agent_ids[1]][2][0]]
+                    # Add the new alliance
+                    best[agent_ids[0]] = [group, value, agent_ids]
+                    best[agent_ids[1]] = [group, value, agent_ids]
+            elif (
+                agent_ids[0] in best
+            ):  # if only agent_ids[0] in, see if it would be trading up
+                if value[0] > best[agent_ids[0]][1][0]:
+                    # Remove the old alliance for agent_ids[0]
+                    del best[best[agent_ids[0]][2][1]]
+                    # Add the new alliance
+                    best[agent_ids[0]] = [group, value, agent_ids]
+                    best[agent_ids[1]] = [group, value, agent_ids]
+            elif (
+                agent_ids[1] in best
+            ):  # if only agent_ids[1] in, see if it would be trading up
+                if value[0] > best[agent_ids[1]][1][0]:
+                    # Remove the old alliance for agent_ids[1]
+                    del best[best[agent_ids[1]][2][0]]
+                    # Add the new alliance
+                    best[agent_ids[0]] = [group, value, agent_ids]
+                    best[agent_ids[1]] = [group, value, agent_ids]
+
+        # Create a unique dictionary of the best combinations
+        unique_combinations = {}
+        for group, value, agents_nums in best.values():
+            unique_combinations[tuple(agents_nums)] = [group, value]
+
+        return unique_combinations.values()
+
+    def step(self):
+        """
+        Execute one step of the model.
+        """
+        # Get all other agents of the same type
+        agent_types = list(self.agents_by_type.keys())
+
+        for agent_type in agent_types:
+            similar_agents = self.agents_by_type[agent_type]
+
+            # Find the best combinations using find_combinations
+            if (
+                len(similar_agents) > 1
+            ):  # only form alliances if there are more than 1 agent
+                combinations = find_combinations(
+                    self,
+                    similar_agents,
+                    size=2,
+                    evaluation_func=self.calculate_shapley_value,
+                    filter_func=self.only_best_combination,
+                )
+
+                for alliance, attributes in combinations:
+                    class_name = f"MetaAgentLevel{attributes[2]}"
+                    meta = create_meta_agent(
+                        self,
+                        class_name,
+                        alliance,
+                        Agent,
+                        meta_attributes={
+                            "level": attributes[2],
+                            "power": attributes[0],
+                            "position": attributes[1],
+                        },
+                    )
+
+                    # Update the network if a new meta agent instance created
+                    if meta:
+                        self.network.add_node(
+                            meta.unique_id,
+                            size=(meta.level + 1) * 300,
+                            level=meta.level,
+                        )
+                        self.add_link(meta, meta.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/Readme.md

@@ -17,13 +17,11 @@ The Demographic Prisoner's Dilemma demonstrates how simple rules can lead to the
 
 ## How to Run
 
-##### Web based model simulation
+To run the model interactively, in this directory, run the following command
 
-To run the model interactively, run ``solara run app.py`` in this directory.
-
-##### Jupyter Notebook
-
-Launch the ``Demographic Prisoner's Dilemma Activation Schedule.ipynb`` notebook and run the code.
+```
+    $ solara run app.py
+```
 
 ## Files
 

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

@@ -42,14 +42,13 @@ The model demonstrates several Mesa concepts and features:
 
 
 ## How to Run
-To run the model interactively:
+
+To run the model interactively, in this directory, run the following command
 
 ```
-  $ solara run app.py
+    $ 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
 
 * `model.py`: The Sugarscape Constant Growback with Traders model.
@@ -58,7 +57,7 @@ Then open your browser to [http://127.0.0.1:8521/](http://127.0.0.1:8521/) and p
 * `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
+## Further Reading
 
 - [Growing Artificial Societies](https://mitpress.mit.edu/9780262550253/growing-artificial-societies/)
 - [Complexity Explorer Sugarscape with Traders Tutorial](https://www.complexityexplorer.org/courses/172-agent-based-models-with-python-an-introduction-to-mesa)

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}",