meta-agent creation

- adds ability to dynamically create meta-agents
- adds alliance formation model to demonstrate
- adds tests to agent.py for meta agent creation

Author: tpike3

mesa/agent.py

@@ -67,7 +67,10 @@ def __init__(self, model: Model, *args, **kwargs) -> None:
         self.unique_id: int = next(self._ids[model])
         self.pos: Position | None = None
         self.model.register_agent(self)
-
+        # Private attribute to track parent agent if metaagents are created
+        # Uses name mangling to prevent name clashes
+        self.__metaagent = None # Currently restricted to one parent agent
+        
     def remove(self) -> None:
         """Remove and delete the agent from the model.
 
@@ -132,7 +135,100 @@ def __getitem__(self, i):
             agent = cls(model, *instance_args, **instance_kwargs)
             agents.append(agent)
         return AgentSet(agents, random=model.random)
+    
+    def create_metaagent(self, new_agent_class: str, agents: Iterable[Agent], **unique_attributes_functions) -> None:
+
+        """Dynamically create a new meta-agent class and instantiate agents in that class.
+
+        Args:
+            new_agent_class (str): The name of the new meta-agent class.
+            agents (Iterable[Agent]): The agents to be grouped into the new meta-agent class.
+            **unique_attributes_functions: A dictionary of unique attributes for that class.
+
+        Returns:
+            Adds the new meta-agent instance to agentset if adding agent to new class or new agent instance
+            - None if adding agent to exsiting class
+            - New class instance if created a new instance of a dynamically created agent type
+            - New class instance if created a new dynamically created agent type
 
+        Notes:
+            This method is useful for creating meta-agents that represent groups of agents with interdependent characteristics.
+            The new meta-agent class is created dynamically using the provided name and unique attributes and functions.
+
+            Currently restricted to one parent agent and one meta-agent per agent. Goal is to assess usage and expand functionality.
+
+            Method has three paths of execution:
+            1. Add agents to existing metaagent
+            2. Create new meta-agent instance of existing metaagent class
+            3. Create new meta-agent class
+
+            See alliance formation example for usage.
+
+        """
+        # Convert agents to set to ensure uniqueness
+        agents = set(agents)
+
+        # Helper function to update agents __metaagent attribute and store agent's metaagent
+        def update_agents_metaagent(agents, metaagent):
+            for agent in agents:
+                agent._Agent__metaagent = metaagent
+  
+        # Path 1 - Add agents to existing meta-agent
+        subagents = [agent for agent in agents if agent._Agent__metaagent is not None]
+        
+        if len(subagents) > 0:
+            if len(subagents) == 1: 
+                # Update metaagents agent set with new agents
+                subagents[0]._Agent__metaagent.agents.update(agents)
+                # Update subagents with metaagent
+                update_agents_metaagent(agents, subagents[0]._Agent__metaagent)
+            else: 
+                # If there are multiple subagents, one is chosen at random to be the parent metaagent
+                subagent = self.random.choice(subagents)
+                # Remove agent who are already part of metaagent
+                agents = set(agents) - set(subagents)
+                subagent._Agent__metaagent.agents.update(agents)
+                update_agents_metaagent(agents, subagent._Agent__metaagent)
+                # TODO: Add way for user to add function to specify how agents join metaagent
+                    
+        else:      
+            # Path 2 - Create a new instance of an exsiting meta-agent class
+            agent_class = next((agent_type for agent_type in self.model.agent_types if agent_type.__name__ == new_agent_class), None)
+            if agent_class:
+                # Create an instance of the meta-agent class
+                meta_agent_instance = agent_class(self.model, **unique_attributes_functions)
+                # Add agents to meta-agent instance
+                meta_agent_instance.agents = agents
+                # Update subagents Agent.__metaagent attribute
+                update_agents_metaagent(agents, meta_agent_instance)  
+                # Register the new meta-agent instance
+                self.model.register_agent(meta_agent_instance)
+
+                return meta_agent_instance 
+                
+            # Path 3 - Create a new meta-agent class
+            else: 
+                # Get agent types of subagents to create the new meta-agent class
+                agent_types = tuple(set((type(agent) for agent in agents)))
+
+                meta_agent_class = type(
+                    new_agent_class,
+                    agent_types,
+                    {
+                        "unique_id": None,
+                        "agents": agents, 
+                    }
+                )
+                
+                # Create an instance of the meta-agent class
+                meta_agent_instance = meta_agent_class(self.model, **unique_attributes_functions)
+                # Register the new meta-agent instance
+                self.model.register_agent(meta_agent_instance)
+                # Update subagents Agent.__metaagent attribute
+                update_agents_metaagent(agents, meta_agent_instance) 
+
+                return meta_agent_instance  
+    
     @property
     def random(self) -> Random:
         """Return a seeded stdlib rng."""

mesa/examples/basic/alliance_formation_model/Readme.md

@@ -0,0 +1,41 @@
+# Alliance Formation Model
+
+## Summary
+
+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 its current configuration, agents being part of multiple meta-agents is not supported 
+
+## Installation
+
+This model requires Mesa's recommended install
+```
+    $ 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/basic/alliance_formation_model/__init__.py

@@ -0,0 +1,58 @@
+import mesa
+
+def calculate_shapley_value(self, other_agent):
+        """
+        Calculate the Shapley value of the two agents
+        """
+        other_agent.hierarchy = other_agent.hierarchy
+        self.hierarchy = self.hierarchy
+        new_position = 1-abs(self.position - other_agent.position)
+        potential_utility = (self.power+other_agent.power)*1.1 * new_position
+        value_me = 0.5 * self.power + 0.5 * (potential_utility - other_agent.power)
+        value_other = 0.5 * other_agent.power + 0.5 * (potential_utility - self.power)
+
+        
+        # Determine ig there is value in the alliance
+        if value_me > self.power and value_other > other_agent.power:
+            if other_agent.hierarchy>self.hierarchy:
+                hierarchy = other_agent.hierarchy
+            elif other_agent.hierarchy==self.hierarchy:
+                hierarchy = self.hierarchy+1
+            else:
+                hierarchy = self.hierarchy
+            
+            return (potential_utility, new_position, hierarchy)
+        else:
+            return None
+
+class alliance_agent(mesa.Agent):
+    """
+    Agent has three attirbutes power (float), position (float) and hierarchy (int)
+    
+    """
+    def __init__(self, model, power, position, hierarchy=0):
+        super().__init__(model)
+        self.power = power
+        self.position = position
+        self.hierarchy = hierarchy
+
+
+    def form_alliance(self):
+        # Randomly select another agent of the same type
+        other_agents = [agent for agent in self.model.agents_by_type[type(self)] if agent != self]      
+        
+        # Determine if there is a beneficial alliance
+        if other_agents: 
+            other_agent = self.random.choice(other_agents)
+            shapley_value = calculate_shapley_value(self, other_agent)
+            if shapley_value:
+                class_name = f"MetaAgentHierarchy{shapley_value[2]}"
+                meta = self.create_metaagent(class_name, {other_agent, self}, hierarchy=shapley_value[2], 
+                                             power=shapley_value[0],position=shapley_value[1])
+                
+                # Update the network if a new meta agent instance created
+                if meta: 
+                    self.model.network.add_node(meta.unique_id, size =(meta.hierarchy+1)*200) 
+                    self.model.new_agents=True
+                else:
+                    self.model.new_agents=False

mesa/examples/basic/alliance_formation_model/agent.py

@@ -0,0 +1,71 @@
+import networkx as nx
+import matplotlib.pyplot as plt
+from matplotlib.figure import Figure
+from mesa.examples.basic.alliance_formation.model import alliance_model
+import solara
+from mesa.mesa_logging import DEBUG, log_to_stderr
+from mesa.visualization.utils import update_counter
+from mesa.visualization import (SolaraViz)
+
+log_to_stderr(DEBUG)
+
+
+
+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.spring_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 = alliance_model(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="Allliance Formation Model",
+)
+page  # noqa

mesa/examples/basic/alliance_formation_model/app.py

@@ -0,0 +1,35 @@
+import numpy as np
+import mesa
+from agent import alliance_agent
+import networkx as nx
+
+class alliance_model(mesa.Model):
+    def __init__(self, n=50, mean=0.5, std_dev=0.1, seed=42):
+        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 = np.random.normal(mean, std_dev, n)
+        power = np.clip(power, 0, 1)
+        position = np.random.normal(mean, std_dev, n)
+        position = np.clip(position, 0, 1)
+        alliance_agent.create_agents(self, n, power, position)
+        agent_ids = [(agent.unique_id, {"size": 100}) for agent in self.agents]
+        self.network.add_nodes_from(agent_ids)
+
+    def add_link(self, metaagent, agents):
+        for agent in agents:
+            self.network.add_edge(metaagent.unique_id, agent.unique_id) 
+
+    def step(self):
+        for agent_class in list(self.agent_types):  # Convert to list to avoid modification during iteration
+            self.agents_by_type[agent_class].shuffle_do("form_alliance")
+
+            # Update graph
+            if agent_class is not alliance_agent:
+                for metaagent in self.agents_by_type[agent_class]:
+                    self.add_link(metaagent, metaagent.agents)  
+                

mesa/examples/basic/alliance_formation_model/model.py

@@ -682,3 +682,40 @@ def custom_agg(values):
     assert custom_result[False] == custom_agg(
         [agent.value for agent in agents if not agent.even]
     )
+
+
+class TestMetaAgent(Agent):
+    def __init__(self, model, power, position, hierarchy=0):
+        super().__init__(model)
+        self.power = power
+        self.position = position
+        self.hierarchy = hierarchy
+
+def test_create_metaagent():
+    model = Model()
+    agent1 = TestMetaAgent(model, power=0.5, position=0.5)
+    agent2 = TestMetaAgent(model, power=0.6, position=0.6)
+    agent3 = TestMetaAgent(model, power=0.7, position=0.7)
+    agent4 = TestMetaAgent(model, power=0.8, position=0.8)
+
+    # Test creating a new meta-agent class
+    meta = agent1.create_metaagent("MetaAgentClass1", {agent1, agent2}, power=1.1, position=0.55, hierarchy=1)
+    assert len(model.agent_types) == 2
+    assert len(model.agents) == 5
+    assert meta.power == 1.1
+    assert meta.position == 0.55
+    assert meta.hierarchy == 1
+
+    # Test adding agents to an existing meta-agent
+    agent1.create_metaagent("MetaAgentClass1", {agent3, agent2}, power=1.8, position=0.65, hierarchy=1)
+    assert len(model.agent_types) == 2
+    assert len(model.agents) == 5
+    assert len(meta.agents) == 3
+
+    # Test creating a new instance of an existing meta-agent class
+    meta2 = agent4.create_metaagent("MetaAgentClass2", {agent4}, power=0.8, position=0.8, hierarchy=2)
+    assert len(model.agent_types) == 3
+    assert len(model.agents) == 6
+    assert meta2.power == 0.8
+    assert meta2.position == 0.8
+    assert meta2.hierarchy == 2