Home

Welcome to the Group8 wiki! Here is how to run the mesa model in our repo: Chinese Ver.

1. Install Git and Clone the Repository

Method 1: Directly Download ZIP Archive

Method 2: Using Git Command Line

First, you need to install Git to get the repository code. Follow these steps to install:

1. Go to the Git official website and download the Git installer for your operating system.
2. After installation, open the command line tool (Windows: CMD/PowerShell; Mac/Linux: Terminal).
3. Run the following command to clone the repository:

git clone https://github.com/EECS4461/Group8.git

Method 3: GitHub Desktop Client

1. Install GitHub Desktop.
2. Open it and press [Ctrl] + [Shift] + [O] to Clone a repo, enter the repository URL: https://github.com/EECS4461/Group8.git.
3. Choose the local path and click Clone.

---

2. Install Python Environment

Check Python Version:

Check if the local Python environment version is >= 3.11 in the terminal:

python -V # or python3 -V

• If the output is Python 3.11.x or higher, skip the installation steps.
• If the version is lower than 3.11, install it as follows:

Method 1: Download the Latest Version from Python Official Website

https://www.python.org/downloads/ Download the installer for your platform.

Method 2: Install Conda to Manage Python Environment (Recommended)

1. Go to the Anaconda official website to download and install Anaconda (which includes Conda). Or install Miniconda (lightweight version).
2. After installation, open the command line tool, create a new Conda environment and activate it:

conda create --name mesa-env python=3.11
conda activate mesa-env

---

3. Install Dependencies

After confirming that Python and pip have been added to the environment variables, or directly using Method 2, install the project dependencies in the activated Conda environment:

1. Switch the working directory to the cloned repository directory in the terminal:

cd /path/to/Group8

2. Run the following command to install dependencies:

pip install -r requirements.txt

• If using Conda, make sure the mesa-env environment is activated (run conda activate mesa-env in the terminal).

---

4. Run the Demo

Finally, you can run the demo in the project:

1. In the repository directory, run the following command to start the demo:

• demo_01 with datacollect chart

  This example demonstrates the statistical table for data collection:

solara run ./src/demo_01.py

• After running, the browser will automatically open http://localhost:8765.

• demo_02 Agents in different colors and shapes

  This example demonstrates defining shapes and colors for different agents:

solara run ./src/demo_02.py

Now, you should see the demo running in the browser. Please refer to the implementation in the demo and the official Mesa documentation and example models, and follow the two simulation design deployment guides in doc/DEL3 to participate in the improvement of the Xiaohongshu model!

5. Mesa Official Documentation and Example Models

Mesa Official Getting Started Documentation

Main Reference Models

Boids Flockers Model

Epstein Civil Violence Model

Example Model Repository

Example models in Repo

Team Organization Forked Mesa Framework Repository

Team Organization Forked Advanced Example Model Repository

---

5. Real-time Interactive Experiments with Jupyter Notebook

Mesa supports running and debugging models in real-time in Jupyter Notebook, allowing you to modify parameters, observe changes, and visualize results instantly. Here are the steps:

Example Jupyter Notebook in the Group Forked Example Model Repository

1. Install Jupyter Notebook

If not installed, run the following command in the terminal (ensure in the Conda environment):

# Install with Conda (recommended)
conda install jupyterlab

# Or install with pip
pip install jupyterlab

2. Start Jupyter Notebook

1. Enter the project directory (cloned repository path) in the terminal:

   cd /path/to/Group8

2. Start Jupyter Lab:

   jupyter lab

3. The browser will automatically open http://localhost:8888, click the Python 3 icon to create a new Notebook.

3. Run Mesa Model in Notebook

Example: Run a Custom Model

1. Enter the following code in a new Notebook cell (example of a simple agent model):

from mesa import Model, Agent
from mesa.time import RandomActivation
from mesa.space import MultiGrid
from mesa.visualization.ModularVisualization import ModularServer

# Define Agent Class
class SimpleAgent(Agent):
    def __init__(self, unique_id, model):
        super().__init__(unique_id, model)
        
    def step(self):
        print(f"Agent {self.unique_id} is taking action")

# Define Model Class
class SimpleModel(Model):
    def __init__(self, N=5, width=10, height=10):
        self.num_agents = N
        self.grid = MultiGrid(width, height, True)
        self.schedule = RandomActivation(self)
        
        # Create Agents
        for i in range(self.num_agents):
            a = SimpleAgent(i, self)
            self.schedule.add(a)
            x = self.random.randrange(self.grid.width)
            y = self.random.randrange(self.grid.height)
            self.grid.place_agent(a, (x, y))

    def step(self):
        self.schedule.step()

# Launch Mesa Visualization Server (render directly in Notebook)
server = ModularServer(SimpleModel, [], "Simple Model", {"N":5, "width":10, "height":10})
server.port = 8521  # Specify port
server.launch()

2. Press Shift + Enter to run the cell.
3. A new tab will automatically open in the browser displaying the model visualization interface (if no popup, manually visit http://localhost:8521).

4. Real-time Interactive Experiments

Modify Parameters and Observe Changes

1. Adjust model initialization parameters in the code (e.g., N=10 to increase the number of agents).
2. Re-run the cell (click the cell and press Shift + Enter).
3. Refresh the browser page to see the updated model.

Add Visualization Components

Add CanvasGrid visualization to the model (example code):

from mesa.visualization.modules import CanvasGrid

def agent_portrayal(agent):
    return {"Shape": "circle", "Filled": "true", "r": 0.5, "Color": "red"}

grid = CanvasGrid(agent_portrayal, 10, 10, 500, 500)
server = ModularServer(SimpleModel, [grid], "Simple Model", {"N":5, "width":10, "height":10})

5. Run Mesa Official Example Models

Boids Flockers (Bird Flock Simulation)

1. Enter the following code in a new Notebook cell:

from mesa.examples import boid_flockers
from mesa.visualization.ModularVisualization import ModularServer

server = ModularServer(boid_flockers.BoidFlockers, [], "Boids Model", {"population": 10})
server.port = 8522  # Avoid port conflict
server.launch()

Epstein Civil Violence Model

from mesa.examples import epstein_civil_violence
from mesa.visualization.ModularVisualization import ModularServer

server = ModularServer(epstein_civil_violence.CivilViolenceModel, [], "Epstein Model")
server.port = 8523
server.launch()

---

Common Issues

1. Notebook Kernel Not Found:
   • Ensure Jupyter Lab is started in the Conda environment: activate the environment and run conda install ipykernel.
2. Missing Dependencies:
   • Install missing packages directly in the Notebook cell: !pip install package-name.

3. Visualization Not Displaying: