Introduction to the ODD Protocol

Overview

brief model overview

Design concepts

approaches to model and experiment design

Details

detailed discussion of the model

This section introduces an ABMS presentation protocol called the ODD protocol. The ODD protocol was introduced by [Grimm.etal-2006-EcolModel] and futher codified by [Grimm.etal-2010-EcolModel]. The following presentation diverges somewhat from these sources. In particular, this section approaches ODD as a useful checklist rather than a rigid protocol.

ODD is an acronym for overview, design concepts, and details. The ODD protocol provides structured guidance to authors for reporting on the design and implementation of agent-based models. It attempts to reconcile two partially conflicting goals: readability, and completeness. Ordinarily, an ODD description (or some other structured exposition) precedes the analysis of ABMS experiments.

Model Overview (PES)

Purpose

short statement of model goals and scope

Entities

short description of model entities

Schedule

state variables and (time and space) scales spatial and temporal scale of model; description of model state

Purpose

Before delving into your model overview, provide a very brief restatement of its purpose and intended scope. Typically the introduction of a report provides a more elaborate statement of purpose, and you may refer back to that. When reporting on a model that is a modification an existing model, mention this dependency in both locations.

Ordinarily the purpose of a model is tightly tied to any experiments described in the report. If relevant, the Purpose section is a good place to mention the time scale and spatial scale of the model. (That is, what real-world period of time will your simulations describe, and over what real-world geographical extent will your model entities be located?) [1]

Model Entities

  • data attributes (mutable and immutable)

  • behavior attributes

  • should usually be supported by UML class diagrams

Next, describe the model agents and other key model objects. In principle, these descriptions may rely be entirely verbal, but it practice they will generally rely on pseudocode or diagrams. In particular, UML class diagrams provide a useful point of reference for the description of agents, even when the model implementation is not object-oriented. In any case, for each type of entity be sure to present the key attributes of the conceptual entities, regardless of their implementations.

  • data attributes (often just called attributes in UML)

  • behavioral attributes (called “operations” in UML)

Describe data atttributes in just enough detail to characterize the essential state of the entity. Specify whether data attributes are mutable (e.g., wealth) or immutable (e.g., sex). Specify behavior attributes in just enough detail to communicate the core entity behaviors, which you will refer to when discussing the simulation schedule. [2] The may be method attributes in an obect-oriented implementation, procedures in a procedural implementation, or functions in a functional implementation. To the extent possible, base your description on the underlying conceptual model rather than on the particular implementation used.

If you are modifying an existing model, distinguish between the entity attributes in the original model and any new attributes you introduce. Use of a UML class diagram can help the discussion become more focused and rigorous.

Process Overview and Scheduling

In the original ODD protocol, the evolution of the simulation model is characterized by a schedule of “processes”. the sequence of interactions (who does what, when).

Model state variables, and (time and space) scales

State Variables

Describe other model state, including:

  • parameters (global constants that control the simulation)

  • model variables (global variables that represent the state of the simulation model)

Spatial and Temporal Scale:

Suggest real-world interpretations of time and space in the model. For example, how much real world time does a single simulation step represent? Similarly, if your model has a spatial aspect (e.g., toplogical patches), what is the real-world corollary to the spatial extent of your model? Specify the stopping condition (under which the iterations of the schedule must stop); the ODD framework refers to this as “temporal extent”

Simulation Schedule: Model State and Evolution

  • characterization of model state

  • may support with pseudocode an/or UML activity diagram

The next step in our ODD report on our model is to desribe how the simulation proceeds over time. Ordinarily, this description refers to the model state and the rules for how that state changes as a simulation runs. Usually you will include a visual representation of the schedule, either as pseudocode or as a rough UML activity diagram. [3]

As a simulation runs, the computational model changes state. Suppose that at some point in a simulation, you wish to stop the simulation and save enough information to correctly continue it later. The information you would need to save constitutes the state of the simulation model at that point.

This state may be adequately captured by the data attributes of the model’s entities, or there the model may have additional state variables (e.g., global variables). For example, there may be a global state of technological productivity, which influences the productivity of individual firms (or its evolution). Describe any model state needed to understand the dynamic evolution of the model.

The evolution of the model state will depend on which behaviors are invoked and in which order. In the simulations of this course, we capture this sequence of events in an iterative simulation schedule. Provide a helpful overview of the simulation schedule. Each pass through the simulation schedule is called a step. Be sure to characterize the time scaled of the simulation as well as you can. This is usually the amount of real-world time that corresponds to one step of our simulation. In more abstract simulations, the corresponding real-world time can be quite vague.

Design Concepts

General design considerations, which will vary substantially by application.

Basic Principles:

State the theories and hypotheses motivating the design.

Emergence:

Emergent results are not evidently imposed by the model. Emergent results are typically patterns produced by the uncoordinated interactions of individual agents. What concept of emergence is relevant to this model, and what results of the model may be considered emergent?

Objectives (goals or filters) and Prediction:

Agent behavior evinces underlying objectives and predictions, at least implicitly. Describe how the agents predict the consequences of behavior. Provide a summary of the agents' goals (objectives) or survival criteria (fitness), and how conflicts between objectives are resolved. Classify objectives as explicit (e.g., explicit utility maximization as a basis of behavior) or implicit (embodied in simple rule-based behavior). Distinguish between the agent’s pursuit of explicit objectives and rule-following behaviors that embody implicit objectives.

Sensing

An agent’s behavior typically depends on its own state and on the state of its environment, which may comprise other agents. Sensing is the ability to detect some of this model state (possibly with error).

Adaptation and Learning

An agent’s behavioral responses to its environment may depend on the agent’s history. Adaptation is a change in behavior due to the influence of the past. The ODD protocal defined adaptation as behavioral change that improves fitness, where fitness is success in achieving favorable outcomes. (The meaning of this is entirely model specific.) We require only that the past affect behavior, not that fitness improve. When describing adaptation, specify the behavioral rules or behavior-guiding objectives that determine such behavior change.

Learning is a kind of adaptation: a change in behavior that results from experience. Describe how experience is accumlated (e.g., as memory, or a genotypical modification) and how it turn into changes in behavior (e.g., by changing beliefs or by changing phenotypical expression). Can an agent “learn the wrong lesson” in the model, and if so, how would this manifest?

Interaction:

What kinds of interactions take place among agents? Distinguish direct interactions between agents from mediated interactions, such as the environmental consequences of one agent’s actions for other agents.

Stochasticity:

Is there any randomness in the model? If so where, and what are the reasons for it? How do you ensure replicability, given this stochasiticy?

Collectives:

Groups of agents with group attributes and group behaviors that affect the individual attributes and behaviors. (E.g., packs of dogs.) A collective contains individuals but is not just a group of individuals.

Observation:

Give a precise description of the entire dataset that you will produce. Explain how these relate to your research question. Also, explain how you will view this data, using plots, charts, regressions, etc.

Be completely explicit which model outcomes will be observed and how. Explain what observational data will be gathered from the model and how (e.g., what variables are written to file, and at what frequency---every iteration, select iterations, or only at the end of the simulation). Finally, explain what tools (charts, statistical tools, etc.) will be applied to the collected data.

Details

  • intialization

  • exogenous inputs

  • submodels

You should provide adequate detail to allow exact replication of your results.

Initialization

Specify the determination of the initial model state. This usually requires a detailed discussion of all setup procedures (and subroutines). Typically, key parts of the initialization depend on model parameters. Try to describe the initialization in terms of values of the parameters. Ordinarily you will introduce a table showing the parameter values for a baseline initialization of the global state. Sometimes you will also need an initialization table for each type of agent in the model.

Some initialized values may be stochastic. If so, specify the distributions from which these values are drawn. (Also, be sure to address replicability: what is required to make a simulation experiment exactly replicable?)

Input Data

If your model will use an external (exogenous) inputs to the model as it runs, specify that here. This will ordinarily be time-series data exogenous to the model that is read in from files as part of the schedule. (It does not include model parameters, even if these are read from file at initialization.)

Submodels

  • details of the schedule components and all your key procedures

  • discussion of any model calibration and experiments

The ODD protocol additionally states that model parameterization may be discussed in this subsection. However, we will ordinarily include a separate section on the baseline parameterization and related experiments.

More About Collectives

The notion of a collective has some ambiguity.

The basic idea is that individuals can belong to groups, where the groups have their own group attributes and group behaviors. The group influences the behavior of the individual. A collective is not just a number of individuals. A collective has its own separate attributes and behaviors, which determine how members of collective behave.

Groups may exist in a model exogenously or endogenously, and groups may be imposed or emergent:

exogenous groups and membership:

e.g., group membership as an fixed agent attribute

exogenous groups and endogenous membership:

e.g., agents join existing political parties

endogenous groups and endogenous membership,

e.g., agents form new political parties, dogs form packs

A collective may be a separate agent, with a list of member agents as an attribute.

Programming Language and Tools

Although the ODD protocol does not specify this, you should always provide full details (including explicit citations) about your choice of programming language, toolkits, and data analysis software. It is often useful to discuss how these choices influenced your implementation of your model.

ODD Protocol: Key Readings

References

[Grimm.etal-2006-EcolModel] (1,2)

Grimm, V., et al. (2006) A Standard Protocol for Describing Individual-Based and Agent-Based Models. Ecological Modelling 198, 115--126. https://www.sciencedirect.com/science/article/pii/S0304380006002043

[Grimm.etal-2010-EcolModel] (1,2)

Grimm, V., et al. (2010) The ODD Protocol: A Review and First Update. Ecological Modelling 221, 2760--2768.

[Polhill-2010-JASSS]

Polhill, J. Gary. (2010) ODD Updated. Journal of Artificial Societies and Social Simulation 13, Article 9. http://jasss.soc.surrey.ac.uk/13/4/9.html

[Polhill.Parker.Brown.Grimm-2008-JASSS]

Polhill, J. Gary, et al. (2008) Using the ODD Protocol for Describing Three Agent-Based Social Simulation Models of Land-Use Change. Journal of Artificial Societies and Social Simulation 11, Article 3. http://jasss.soc.surrey.ac.uk/11/2/3.html

Copyright © 2016–2022 Alan G. Isaac. All rights reserved.

version:

2022-08-04