Mesa Documentation

The Epstein Civil Violence Model is an agent-based simulation of how civil unrest grows and is suppressed.

Key Components:

• Citizen Agents: Wander a grid with individual risk aversion and hardship levels. They decide to rebel based on hardship, regime legitimacy, and perceived arrest probability.
• Cop Agents: Work on behalf of the regime to arrest Citizens who are actively rebelling.
• Regime Legitimacy: A universal value that influences agent behavior.

Dynamics:

• Mass Uprising: A self-reinforcing process where high numbers of rebels reduce the individual probability of arrest, encouraging more agents to join.
• Suppression: Increased arrests by Cops reduce the likelihood of additional agents joining the uprising.

This model is an implementation of Epstein & Axtell's Sugarscape model. It demonstrates emergent price equilibrium through decentralized dynamics using multiple agent types and a resource landscape.

Key Agent Types

• Resource Agents: Grow back at one unit of sugar and spice per time step up to a specified maximum. They can be harvested and traded.
• Traders: Agents with sugar/spice metabolism, vision, and initial endowments. They move across the landscape to harvest resources and trade with others. If they run out of sugar or spice, they are removed from the model.

Model Features Demonstrated

• Use of OrthogonalMooreGrid.
• Implementation of multiple agent types (traders, sugar, spice).
• Dynamic removal of agents from the grid and schedule upon death.
• Data Collection at both the model and agent levels.
• Custom Solara and Matplotlib space visualization.

The Boids Flockers example is organized into three main files:

• model.py: Contains the Boid Model implementation.
• agents.py: Contains the Boid agent logic.
• app.py: Contains the Solara-based visualization code.

Mesa supports meta-agents, which allow you to represent hierarchical complex systems. A meta-agent is a higher-level entity composed of sub-agents (e.g., an organization made of departments, or a robot made of autonomous components).

Key capabilities include:

• Dynamic Class Creation: Mesa can dynamically create new classes of agents composed of existing agents.
• Inheritance: Meta-agents can inherit functions and attributes from their sub-agents.
• Customization: Users can specify new functionality or attributes for the meta-agent level.

Limitations: In the current configuration of the MetaAgent implementation demonstrated in this model, an agent cannot be part of multiple meta-agents simultaneously.

This example follows Mesa's standard separation of concerns across several files:

• agents.py: Defines individual agent behavior (e.g., WealthAgent and its step method).
• model.py: Manages the simulation environment, instantiates agents, handles the grid/space, and collects data (e.g., using Mesa's DataCollector).
• app.py: Sets up visualization components for a web interface (Solara).
• st_app.py: (Optional) An alternative Streamlit-based visualization.

The Virus on a Network model implements the SIR epidemiological model to demonstrate how a virus spreads through a network. The population is divided into three compartments:

• S (Susceptible): Individuals who can contract the disease upon contact with an infectious individual.
• I (Infectious): Individuals who have been infected and can spread the disease to susceptible individuals.
• R (Removed/Recovered/Resistant): Individuals who have either recovered and gained immunity or have died. In this model, deaths are assumed to be negligible.

After installing the recommended dependencies, you can launch the interactive visualization server for the Wolf-Sheep Predation model using Solara:

solara run app.py

The Boltzmann Wealth Model is a tutorial example demonstrating agent wealth exchange. To run the interactive visualization provided in this example, install Mesa with the recommended dependencies and use the solara command.

1. Install Mesa with recommended dependencies:

   pip install "mesa[rec]"

2. Run the application:

   solara run app.py

3. Open the local URL displayed in your terminal in a web browser.

To maintain consistency and follow Mesa best practices, organize your model into a directory named with lower-case letters and underscores (e.g., wolf_sheep). Use the following file structure:

• Readme.md: Model description and usage instructions.
• model.py: Contains the Model class.
• agents.py: Contains the Agent class(es).
• app.py: (Optional) Contains Solara-based visualization code.
• run.py: (Optional) Code to execute the model.
• analysis.py: (Optional) Analysis code.

You can also use subdirectories for data management, such as data/, output/, results/, or images/.

To run the Alliance Formation Model (a meta-agent demonstration), you must first install Mesa with the recommended dependencies and then execute the Solara application script.

1. Install Mesa with recommended dependencies:

   pip install "mesa[rec]"

2. Run the application using Solara:

   solara run app.py

3. Open the local URL provided in your terminal in a web browser to view the interactive visualization.