Meta agents

[tpike3]

Summary

This PR is useful for creating meta-agents that represent groups of agents with interdependent characteristics.

New meta-agent classes are created dynamically using the provided name, attributes and functions of sub agents, and unique attributes and functions.

supersedes #2561

Motive

This method is for dynamically creating new agents (meta-agents).

Meta-agents are defined as agents composed of existing agents.

Meta-agents are created dynamically with a pointer to the model, name of the meta-agent,
iterable of agents to belong to the new meta-agents, any new functions for the meta-agent,
any new attributes for the meta-agent, whether to retain sub-agent functions,
whether to retain sub-agent attributes.

Examples of meta-agents:

• An autonomous car where the subagents are the wheels, sensors,
  battery, computer etc. and the meta-agent is the car itself.
• A company where the subagents are employees, departments, buildings, etc.
• A city where the subagents are people, buildings, streets, etc.

Currently meta-agents are restricted to one parent agent for each subagent/
one meta-agent per subagent.

Goal is to assess usage and expand functionality.

Implementation

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

Added meta_agents.py in experimental
Added tests in test-agent.py
Added alliance formation model in basic examples

Usage Examples

I added a basic example of alliance formation using the bilateral shapley value

Step 0- 50 Agents:

Step 8 - 17 Agents of increasing hierarchy added dynamically during code execution:

Additional Notes

Currently restricted to one parent agent and one meta-agent per agent. Goal is to assess usage and expand functionality.

[github-actions]

Performance benchmarks:

Model	Size	Init time [95% CI]	Run time [95% CI]
BoltzmannWealth	small	🔵 -3.6% [-5.2%, -1.9%]	🔵 +0.4% [+0.3%, +0.6%]
BoltzmannWealth	large	🔵 -0.2% [-1.7%, +0.7%]	🔵 -0.3% [-0.6%, +0.1%]
Schelling	small	🔵 -0.2% [-0.4%, +0.1%]	🔵 +0.1% [+0.0%, +0.2%]
Schelling	large	🔵 +0.1% [-0.3%, +0.5%]	🔵 -0.4% [-0.9%, +0.1%]
WolfSheep	small	🔵 +0.5% [+0.0%, +1.0%]	🔵 -1.4% [-6.2%, +3.6%]
WolfSheep	large	🔵 +0.8% [-0.4%, +1.6%]	🔵 -1.6% [-2.6%, -0.7%]
BoidFlockers	small	🔵 +1.3% [+0.9%, +1.9%]	🔵 -0.6% [-1.4%, +0.2%]
BoidFlockers	large	🔵 +1.8% [+0.8%, +2.7%]	🔵 -0.5% [-1.1%, +0.1%]

[EwoutH]

Did you consider incorporating the AgentSet into Meta-agents one way or another (inheritance, composition or otherwise)?

[tpike3]

Did you consider incorporating the AgentSet into Meta-agents one way or another (inheritance, composition or otherwise)?

I did, however just to get meta-agents started and integrated I avoided it since it will add a layer of complications and I was worried about collisions and MRO issues -- Ways forward in no particular order are add AgentSet so each meta-agent has the AgentSet functionality, integrate threading so meta-agents can be on their own thread in 3.13 forward, allow for greater combinatorics (e.g. agents can be in multiple meta-agents)

[EwoutH]

Cool, I will try to dive in and do a proper review tomorrow or Monday.

[jackiekazil]

I am playing catch-up on this. This is interesting. I do not have strong opinions on the setup, and I feel like @EwoutH and @quaquel have it covered.

Question for everyone regarding adding an example in the core examples folder: If memory serves me correctly -- we were adamant about only having five examples with ones that build off of those for maintenance purposes. In what cases do we justify an additional example to the core folder as opposed to the examples folder? (I ask because our original examples folder grew to the maintenance issue that it is because we were trying to demonstrate all the functionality we had in at least one location).

[tpike3]

I am playing catch-up on this. This is interesting. I do not have strong opinions on the setup, and I feel like @EwoutH and @quaquel have it covered.

Question for everyone regarding adding an example in the core examples folder: If memory serves me correctly -- we were adamant about only having five examples with ones that build off of those for maintenance purposes. In what cases do we justify an additional example to the core folder as opposed to the examples folder? (I ask because our original examples folder grew to the maintenance issue that it is because we were trying to demonstrate all the functionality we had in at least one location).

Well clearly I am going to have a bias on this, however, I did consider the challenge of an excess of core examples and the reason I built in basic examples as an exception is because as far I know this would be a unique capability of Mesa compared to NetLogo, MASON etc. Putting it in the basic examples would make it more prominent and easier for users to see, ideally further increasing Mesa's competitiveness as the ABM library of choice.

A second option would be putting it in mesa-examples and then adding some documentation in getting started.

Or I could just put it in Mesa-examples.

I am good with whatever the group decides, just let me know.