Chapter 3 - Your first Mesa model

Chapter 3 - Your first Mesa model#

Video overview

This short video introduces the model-building journey you will follow in Chapter 3.

Chapters 1 and 2 covered what agent-based models are and why they work. Chapter 3 is where you build one, from an empty file to a complete, working model.

Learning objectives

By the end of this chapter, you will be able to:

  1. Build a complete agent-based model in Mesa from scratch, defining an agent class and a model class.

  2. Give agents behaviour and step the model through time, using a random seed for reproducibility.

  3. Add space so that agents can sense and interact with their neighbours.

  4. Collect data during a run with Mesa’s DataCollector, and visualise the results.

  5. Manage groups of agents with AgentSet, run parameter sweeps with a batch run, and analyse the output with pandas.

In a nutshell

You will build one model in eight small additions: start with bare agents, give them a washing decision, place them in a neighbourhood, then measure, visualise, group, sweep, and analyse. Each addition introduces exactly one Mesa idea, so nothing arrives all at once.

In this chapter you build your first complete agent-based model in Mesa, one piece at a time. The running example is household washing coordination: each household decides when to run its washing machine, and you will watch coordinated behaviour emerge from a few simple rules. Along the way you will meet every core Mesa feature you need for the models in Chapter 4, from agents and scheduling to space, data collection, visualisation, batch runs, and analysis with pandas.

Household washing coordination

A hands-on, step-by-step tutorial: set up the model, add behaviour and space, collect and visualise data, run batch experiments, and analyse the results with pandas.

3.1: Household washing coordination

Press Play to watch a neighbourhood drift from chaotic, all-at-once washing into coordinated clusters, the very pattern you will build across this chapter.

Watch washing coordination emerge

Every household follows one selfish habit (wash once the pressure builds), yet a gentle nudge from washing neighbours quietly pulls the timing together. No planner, no schedule, just local rules.

Step 0 · 0 households washing

Households washing over the last 24 steps

washing waiting
Why this matters: watch the little bars. An early, all-at-once spike (everyone crossing their threshold together) gives way to a gentler, rolling wave as neighbours desynchronise into clusters. That shift from noise to pattern, produced by simple local rules, is exactly the behaviour you will model step by step in this chapter.

Begin with the household washing tutorial and build the model one piece at a time.