---

name: mesa description: "Use Mesa for agent-based simulation models, spatial ABM environments, experiment data collection, scenarios, and Solara visualization workflows." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Mesa

Use this repo skill when a task involves Mesa, the Python agent-based modeling framework: building ABM models, managing agents, adding spaces, collecting outputs, running scenarios, or creating browser/notebook visualizations.

Install and import

Mesa requires Python 3.12 or newer in this snapshot.

python -m pip install -U mesa
# For Mesa 4 pre-releases when a task depends on APIs from this skill:
python -m pip install -U --pre mesa
# Recommended optional stacks:
python -m pip install -U "mesa[network]"  # Network spaces
python -m pip install -U "mesa[viz]"      # Solara/matplotlib/altair visualization
python -m pip install -U "mesa[rec]"      # network + viz recommended extras

Minimal import check:

import mesa
from mesa import Agent, DataCollector, Model
from mesa.discrete_space import OrthogonalMooreGrid

Run scripts/check_mesa_install.py for a safe JSON probe of the installed package and optional extras.

Route by task

Task intent	Read
Define Model and Agent classes, create agents, activate AgentSets, seed RNGs, schedule events, run time, remove agents	model-core
Choose grids/cells/network/Voronoi/continuous spaces, move cell agents, use property layers, debug capacity or coordinates	spaces
Collect model/agent/table outputs, create DataFrames, run scenarios, use experimental recorders/actions/states/signals	analysis-experiments
Build or debug SolaraViz, SpaceRenderer, component builders, portrayal styles, plots, user parameters, visualization extras	visualization

High-signal Mesa rules

• In Mesa 4, Agent.__init__(model) automatically registers the agent and assigns unique_id. Do not reassign or manually mutate model.agents.
• Model(rng=...) creates both model.rng and model.random; pass rng for reproducibility unless a Scenario instance already owns the RNG.
• Model.step() is scheduled by default every 1.0 time units; use run_for() or run_until() to process the event queue.
• Prefer model.agents.do(...), shuffle_do(...), map(...), select(...), groupby(...), and agg(...) over custom scheduler objects.
• For new spatial models, use mesa.discrete_space or mesa.experimental.continuous_space, not legacy mesa.space APIs.
• DataCollector supports model, agent, agent-type, and table outputs; avoid lambdas when the model must be pickle-safe.
• SolaraViz re-creates models from model_params; model constructors must accept keyword arguments matching those parameter keys.

Optional dependency choices

• Core modeling, data collection, grids, Voronoi, and continuous spaces: base mesa install.
• Network examples or Network default layouts: install mesa[network] or pass your own graph/layout stack.
• Browser/notebook visualization: install mesa[viz] or mesa[rec].
• Example-library and verification-style runs: mesa[examples] includes recommended extras and pytest.
• Browser end-to-end checks need additional frontend/browser tooling and are not required for ordinary modeling tasks.

References and checks

• references/repo-provenance.md records the source snapshot used to create this skill; read it before deciding whether to refresh the skill for a different checkout or Mesa version.
• references/examples-index.md maps classic Mesa example patterns to the owning sub-skills.
• references/troubleshooting.md covers cross-cutting install, version, optional-extra, and workflow-selection issues.
• Each sub-skill links its own API reference, workflows, troubleshooting guide, and smoke scripts.

Avoid this skill when

• The task is only generic Python, pandas, NumPy, NetworkX, Matplotlib, Altair, or Solara usage without Mesa model objects or Mesa visualization components.
• The task asks for a non-Mesa ABM framework such as NetLogo, Repast, MASON, Agents.jl, or a custom simulator.
• The task is benchmark-scale performance tuning or browser automation infrastructure; this skill records those as long-tail or optional areas, not primary guidance.