alterlab-abm-mesa

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__(rng=...). Mesa 3.5 deprecated the seed= keyword in favor of rng= (same behavior, but seed= now emits a FutureWarning), so new code passes rng=.

import mesa

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

    def step(self):
        if self.wealth > 0:
            other = self.random.choice(self.model.agents)
            other.wealth += 1
            self.wealth -= 1

class MoneyModel(mesa.Model):
    def __init__(self, n=10, rng=None):
        super().__init__(rng=rng)              # mandatory; rng= replaces seed= (Mesa 3.5)
        MoneyAgent.create_agents(self, n)      # bulk creation helper
        self.datacollector = mesa.DataCollector(
            model_reporters={"Gini": compute_gini},
            agent_reporters={"Wealth": "wealth"})

    def step(self):
        self.datacollector.collect(self)
        self.agents.shuffle_do("step")         # replaces RandomActivation

• Scheduling: model.agents.shuffle_do("step") (random activation), model.agents.do("step") (fixed order), do("step") then do("advance") (simultaneous), model.agents_by_type[Type].shuffle_do("step") (staged). model.steps auto-increments.
• Space: classic mesa.space.MultiGrid/SingleGrid/NetworkGrid (maintenance mode) with place_agent/move_agent; new cell space mesa.discrete_space.OrthogonalMooreGrid((w,h), torus=...) / OrthogonalVonNeumannGrid / HexGrid.
• Batch sweeps: mesa.batch_run(MoneyModel, parameters={"n":[10,50,100]}, rng=range(20), max_steps=100, data_collection_period=-1) → list of dicts; each rng value seeds one replicate (iterations= is deprecated since Mesa 3.4).
• Visualization: from mesa.visualization import SolaraViz, make_space_component, make_plot_component.

Full validated skeleton (Schelling + a network model), the space-API choice, and the validation checklist: references/mesa_patterns.md.

The validation discipline

An ABM that runs is not evidence. Report:

1. Replication — multiple runs with different seeds; report the distribution of the macro outcome, not one run (fix rng= for reproducibility, vary it for the distribution).
2. Parameter sweep — batch_run across the key parameters; show how the emergent outcome depends on them (phase transitions, tipping points).
3. Pattern-oriented validation — does the model reproduce the target stylized fact it was built to explain (e.g. Schelling's high segregation from mild preferences)?
4. Sensitivity — which assumptions drive the result; state them.

Output Template

MODEL:       <agents, their state, the local step rule; space = grid/network/none>
SCHEDULE:    <shuffle_do / do / staged> (Mesa 3 AgentSet)
MACRO OUTCOME: <the emergent quantity the DataCollector tracks>
VALIDATION:  <n seeds -> distribution; batch_run sweep; target pattern reproduced?>
CLAIM SCOPE: generative (a sufficient micro mechanism), NOT the unique/true mechanism

References

• references/mesa_patterns.md — validated Mesa 3 skeletons (grid + network), space-API selection, batch_run sweep, validation checklist.

Part of the AlterLab Academic Skills suite.