alterlab-abm-mesa

name	alterlab-abm-mesa
description	Builds agent-based models of social systems with Mesa 3 — the current AgentSet API (model.agents.shuffle_do('step'), auto-assigned unique_id, mandatory super().__init__(seed=...)), cell spaces (mesa.discrete_space OrthogonalMooreGrid / classic mesa.space grids), the DataCollector, batch_run parameter sweeps, and SolaraViz — for emergence, segregation, diffusion, opinion dynamics, and cooperation models. It uses the Mesa 3.x API (the old mesa.time schedulers like RandomActivation are removed) and treats the model as a generative theory to be validated, not just run. Use when the request mentions an agent-based model, Mesa, simulating interacting agents, or emergent macro behavior from micro rules. For discrete-event (queueing/process) simulation prefer alterlab-simpy; for reinforcement learning prefer alterlab-stable-baselines3. Part of the AlterLab Academic Skills suite.
license	MIT
allowed-tools	Read Bash(python:*)
compatibility	Requires mesa>=3 (pip; API changed substantially from Mesa 2 — mesa.time schedulers removed). Optional SolaraViz for interactive visualization. No API key; runs locally via `uv run python`. On the Anthropic API (no runtime install) declare mesa as a dependency.
metadata	{"skill-author":"AlterLab","version":"1.0.0","depends_on":"alterlab-ssci-design-gate, alterlab-simpy (contrast: discrete-event); audited by alterlab-ssci-inference-gate"}

Agent-Based Modeling with Mesa 3 — Micro Rules, Macro Emergence

Skill type: ANALYSIS MODULE. Builds ABMs where macro patterns emerge from local agent rules (Schelling segregation, opinion dynamics, diffusion, cooperation). The discipline: use the current Mesa 3 API, and treat the model as a generative explanation that must be validated (swept, replicated, compared to a target pattern), not a toy that merely runs.

Core Mission

THE MODEL IS A THEORY OF HOW MACRO EMERGES FROM MICRO. USE MESA 3 CORRECTLY, THEN VALIDATE.

When to Use This Skill

• "Build an agent-based model / Mesa model of [segregation, diffusion, opinion, cooperation]."
• "Simulate many interacting heterogeneous agents and watch what emerges."
• "Do a parameter sweep over my ABM and collect outcomes."

Does NOT Trigger

The request is really about…	Route to	Why not this skill
Discrete-event / queueing / process simulation	alterlab-simpy	Event-driven processes, not interacting agents on a grid/network.
Reinforcement learning (an agent learning a policy)	alterlab-stable-baselines3	Policy optimization, not generative social simulation.
Whether ABM is the right method at all	alterlab-ssci-design-gate	Design routing, upstream.
System-dynamics / ODE compartment models	alterlab-statistical-analysis	Aggregate dynamics, not agent-level.

The Mesa 3 API (verified — do not ship Mesa 2 patterns)

Mesa 3 removed mesa.time schedulers (RandomActivation, etc.). Agents auto-register into model.agents; unique_id is auto-assigned; the model must call super().__init__(seed=...).

import mesa

class MoneyAgent(mesa.Agent):
    def __init__(self, model):                 # NO unique_id argument in Mesa 3
        ().__init__(model)
        .wealth = 

     ():
         .wealth > :
            other = .random.choice(.model.agents)
            other.wealth += 
            .wealth -= 

 (mesa.Model):
     ():
        ().__init__(seed=seed)            
        MoneyAgent.create_agents(, n)      
        .datacollector = mesa.DataCollector(
            model_reporters={: compute_gini},
            agent_reporters={: })

     ():
        .datacollector.collect()
        .agents.shuffle_do()