Getting Started with Mesa

Mesa is an agent-based modeling framework for Python. With Loom's Mesa module (31 base nodes, plus 15 optional Mesa Geo nodes), you can build Mesa models visually — defining agents, behaviors, and data collection on a canvas, then generating runnable Python code.

What You'll Build

A Mesa model in Loom consists of:

  • A grid space where agents live and move
  • One or more agent archetypes with properties and behaviors
  • Optional data collectors to track metrics over time
  • Optional scenario parameters to make your model configurable

The Editor

When you open a Mesa project, the editor has a left panel and a graph canvas. The left panel shows:

  • Archetypes — Your agent types (click + to add)
  • Behaviors — Visual graphs for the selected archetype
  • Properties — Data fields on the selected archetype
  • Scenario Parameters — Model-level configurable values (appear as sliders in visualization)
  • Data Collectors — Metrics to track over time
  • Interface Contract — Input/output ports for federation (advanced)

Loom generates Mesa 3.x code using MultiGrid for the spatial grid and Solara for browser-based visualization.

Creating Agents

  1. In the left panel, click + next to Archetypes
  2. Double-click the archetype name to rename it (e.g., "Walker")
  3. Add properties if needed (e.g., "energy" as a float)

Building Behaviors

Each archetype can have multiple behaviors. A behavior is a visual graph that runs once per simulation step. Click Add Behavior to create one, then build logic using nodes.

Common first behavior: connect Entry → Moveto make agents walk randomly.

Running Your Model

After generating code, install Mesa and run:

pip install mesa[viz] solara
solara run app.py

This launches a browser-based visualization with play/pause controls, step-by-step execution, and parameter sliders.