Designing and Documenting Models:
The ODD Protocol

EES 4760/5760

Agent-Based & Individual-Based Computational Modeling

Jonathan Gilligan

Class #4: Thurs. January 18 2018

Housekeeping at Start of Class:

Getting Started:

Today’s slides are at

Designing and Documenting Models

Designing and Documenting Models

ODD publication


  • Don’t start writing code until you know what you’re trying to do.
  • Big picture
    • What is the purpose of your model?
    • What things does your model use?
    • How do those things behave?
  • Design concepts
    • How do you represent the things in your model?
    • How do you implement their behavior?
    • How will your things and behaviors realize your purpose?
    • What data will you collect from your model?
    • How will you use that data to achieve your purpose?

Overview, Design Concepts, and Details

ODD Diagram




ODD in perspective:

  • Write overview and major parts of design concepts first
  • As you write the model code, revisit and revise design concepts.
  • Much of the details will emerge in the course of programming.
  • When you are finished, write a complete ODD. This will be the major documentation for your model.

ODD Outline

1. Purpose

Question: What is the purpose of the model?

2. Entities, State Variables, Scale

  • What kinds of entities are in the model?
    Agents, collectives, spatial units, global environment, …
  • What attributes (state-variables) characterize the entities?
    Age, sex, wealth, mood, opinion, soil type, land costs, rainfall, market price, …
  • What are the temporal and spatial resolutions and extents of the model?

3. Process Overview and Scheduling

  • How do states change?
  • What entities do what, and in what order?
    • Schedule:
      1. Which entities take actions?
      2. What actions do they take?
      3. In what order do they take them?
  • How is time modeled?
    • Discrete steps?
    • Continuum, with both continuous processes and discrete events?

4. Design Concepts

4. Design Concepts

There are 11 design concepts.

Textbook has one chapter for each.

Outline of Design Concepts

  • Basic Principles: Basis of model in general concepts and theories
  • Emergence: What emerges as the model runs?
    (phenomena not imposed or directly programmed)
  • Adaptation How do agents respond to changes in their environment?
    What decisions do they make, and how do they decide?
    Do they seek objectives directly (deliberatly) or indirectly (mimic natural behavior)?
  • Objectives (Fitness): Goals of agents? What determines survival?
    Do objectives change as agent changes?
  • Learning: Do individuals change behavior as they gain experience?
  • Prediction: How do agents predict consequences of their decisions?
    (learning, memory, environmental cues, programmed assumptions)
  • Sensing: What do agents know or perceive when making decisions?
    (Is sensing process itself explicitly modelled, or do they just know?)
  • Interaction: What forms of interaction among agents are there?
  • Stochasticity: Is there randomness in model? Randomness must be justified!
  • Collectives: Grouping of individuals (Herds, social networks, …)
  • Observation: How are data collected from model for analysis?


5. Initialization

  • What is the initial state of the model world?

  • Time \(t = 0\) of a simulation run

  • In detail:
    • How many entities, of what type, are there initially?
    • What are the exact values of their state variables?
      (Or how were they set at random?)
    • Is initialization always the same,
      or does it vary from one simulation run to the next?
    • Are initial values chosen arbitrarily, or based on data?
    • References to those data should be provided.

6. Input data

Does the model use input from external sources
(data files, other models, human interaction)
to represent processes that change over time?

If so, what data?

Where did they come from?

Provide references, citations.

7. Submodels

If the process scheduling step contains a list of processes,
explain, in detail what submodels represent those processes.

What are the model parameters?

How were the submodels designed or chosen?

How were they tested?

Example: Virtual Corridors for Conservation Management

Example: Virtual Corridors for Conservation Management

Virtual Corridors Paper

Pe’er, G., D. Saltz, and K. Frank, “Virtual corridors for conservation management,” Conservation Biology 19, 1997 (2005).


  • Ecologists observe that as butterflies move uphill, they concentrate into narrow and well-definied virtual corridors rather than following any old path to the top of the hill.

  • Explore the concept of virtual corridors:

    Can concentrations of migrating animals emerge spontaneously from movement behavior and topography, instead of being a special habitat?

  • Specifically, How does the concentration of hill-topping butterflies emerge from:
    • How butterflies move uphill
    • Landscape topography

Entities, State Variables, and Scales

  • Landscape:
    • Square grid cells, with one state variable: elevation.
  • Butterflies:
    • Have one state variable: location
      (discrete: which patch they’re in)

Entities, State Variables, and Scales

  • Spatial Scale:
    • 150 × 150 cells
    • Corresponds to 25 × 25 meters in real landscape
  • Time Scale:
    • Simulations last 1000 ticks
    • Tick length is unspecified (time for a butterfly to move one cell).

Process Overview and Scheduling

  • Only one process: butterfly movement
    • On each tick, each butterfly moves once
    • The order in which butterflies move is unimportant because they don’t interact

Design concepts (important ones)

  • Emergence: results (concentration of butterflies in corridors)
    emerge from movement rule and topography
  • Sensing: Butterflies can sense elevation in current and 9 surrounding cells
  • Interaction: None
  • Stochasticity: Used to represent reasons why butterflies do not move straight uphill
  • Observation: We need a way to measure of butterfly concentration


  • Landscape: cell elevations set to flat landscape with two conical hills
  • Butterflies: 500 are created and placed in one cell

Butterfly landscape plan

Butterfly landscape elevation

Submodel: Butterfly movement

  • Global parameter q is probability that butterfly moves straight uphill,
    vs. moving to random neighbor cell.

Butterfly patch movement

Extra Material

Example: flocks of starlings

  • Thousands of individuals
    • unique and different
    • interact locally
    • show adaptive behavior


Flock of thousands of starlings

Simulated flock of thousands of starlings

Simulated flock of thousands of starlings

Adaptive behavior:
Characteristic patterns in trout habitat selection


Adaptive behavior:
Characteristic patterns in trout habitat selection

  • Use of shallow habitat when small; deep habitat when big
  • Shift in habitat when predators, larger competitors are introduced
  • Hierarchical feeding: big guys get the best spots
  • Movement to margins during floods
  • Use of slower, quieter habitat in high turbidity
  • Use of lower velocities at lower temperatures

Source: Railsback and Harvey, 2002.