The following contains the guidance to using the ODD (Overview, Design concepts, Details) Protocol’s newest version, as described in Grimm et al. 2020.

As of 2025-09-11, it is missing part of the examples. Up to date DYNAMO index is here.

ODD Protocol 2020

From Supplementary file S1 to: Grimm, V. et al. (2020) ‘The ODD Protocol for Describing Agent-Based and Other Simulation Models: A Second Update to Improve Clarity, Replication, and Structural Realism’

In brief

ODD is a standard protocol for describing Individual Based Models (IBMs) and Agent-Based Models (ABMs) The protocol consists of three blocks (Overview, Design concepts, and Details), which are (in the 2020 version) subdivided into seven elements: Purpose and patterns, State variables and scales, Process overview and scheduling, Design concepts, Initialization, Input data, and Submodels.

In list form, ODD (2020) contains the following elements:

1. Purpose and patterns (what the model is for, when it is good)
2. Entities, state variables, and scales (the things represented in the model; the ontology)
3. Process overview and scheduling (what the model does as it executes)
4. Design concepts (how the 11 concepts that characterize ABMs were implemented in the model) Basic principles (general concepts, theories, approaches) Emergence (behavior that emerges instead of being imposed) Adaptation (decisions agents make in response to stimuli) Objectives (how decision alternatives are evaluated) Learning (how agents change their decision-making methods) Prediction (how agents predict future conditions) Sensing (what information agents know and use) Interaction (kinds of interaction, incl. communication) Stochasticity (how model uses stochastic processes) Collectives (what aggregations exist, how they’re modeled) Observation (how data is collected and analyzed)
5. Initialization (everything required to set up the model)
6. Input data (what input data is used and how)
7. Submodels (reproducible descriptions of submodels)

Table: The Blocks and Elements of ODD (2020)

Citing the ODD protocol

We ask you to precede your model description with this text: “The model description follows the ODD (Overview, Design concepts, Details) protocol for describing individual- and agent-based models (Grimm et al. 2006), as updated by Grimm et al. (2020).”

The citation of Grimm et al. (2006) will allow us to quantify, review, and improve the use of ODD over time.

The second citation tells readers which version of ODD you follow.

Further discussion

You can find further in-depth discussion of ODD and its elements in Grimm and Railsback (2005) and Railsback and Grimm (2019). While the book of Grimm and Railsback (2005) was written before ODD was established, its Chapter 5 provides the most comprehensive explanation of most of the Design concepts (Element 4), focused on ecological models but still useful for other kinds of models. The textbook of Railsback and Grimm (2019) dedicates many chapters to understanding elements of ODD and implementing them in models, using the same version of ODD as this document.

Please keep these goals of ODD in mind:

• Making model descriptions complete and accurate: it should be possible to reproduce your entire model from its written description.
• Standardizing descriptions for the benefit of users and reviewers: follow the protocol carefully, do not skip elements, and do not make ad hoc changes. It is good, not bad, to copy wording directly from this document. For example, the checklist for Element 1 includes describing “The patterns used as criteria for evaluating the model’s purpose” so we encourage you to start this description with exactly those words. (Of course, you should not copy text from the examples we provide from other people’s publications.)
• Providing an overview first, with details in the last three elements. This guidance and the checklists ask for a great amount of information, but ODD is intended to be hierarchical. The “Overview” elements, 1-3, should provide an accurate overview, but full details of model processes should only appear in elements 5-7.
• Encouraging modelers to think about why they made their design decisions. Describing the rationale for the design is not required by ODD but strongly recommended because it makes the model seem less arbitrary and because it encourages you to think about alternative model designs and select among them carefully. The checklists therefore include reminders to document rationale.

1. Purpose and patterns

Every model has to start from a clear question, problem, or hypothesis; readers cannot understand your model unless they understand its purpose.

Therefore, ODD starts with a concise and specific statement of the purpose(s) for which the model was developed.

The examples of Element 1 we provide below categorize model purposes into types of general purpose (e.g., prediction, explanation, description, theoretical exposition, illustration, analogy, and social learning). It is useful to first identify one or more of these general types of model purpose before stating the specific purpose.

The “patterns” part of this element is new in this version of ODD. It helps clarify the model purpose by specifying the criteria you will use to decide when your model is realistic enough to be useful for its purpose.

The patterns are observations, at the individual or system level, that are believed to be driven by the same processes, variables, etc. that are important for the model’s purpose. For some of the possible purposes, the model will be assumed useful only if it can reproduce the patterns. For other purposes, not reproducing the patterns can be an important result because it indicates that some mechanism is missing or inadequately represented. These patterns can be observations from the real system being modeled, obtained from data or literature.

For models not based on a specific real system, the patterns are often general beliefs about how the system and its agents should behave. Including patterns in ODD is also a way to link it explicitly to “pattern-oriented modeling”, a set of strategies for designing and evaluating ABMs; this link is explained in the main text and by Railsback and Grimm (2019).

Guidance

Make the purpose specific, addressing a clear question. The purpose statement should be specific enough to enable a reader to independently judge a model’s success at achieving this purpose as well as to serve as the primary “filter” for what is and is not in the model: ideally the model should only include entities and mechanisms that are necessary to meet its purpose. If the purpose statement is only general and unspecific, and especially if it lacks patterns for evaluating the model’s usefulness, then it will be difficult to justify (and make) model design decisions.

Some ODDs state only that the model’s purpose is to “explore,” “investigate,” or “study” some system or phenomenon, which is not specific enough to assess the model or to determine what the model needs to contain. An imprecise purpose such as this is often an indication that the modeler simply assembled some mechanisms in an ABM and explored its results. Studies like this can be made more scientific by stating the purpose as a clear question such as “To test whether the mechanisms A, B, and C can explain the observed phenomena X, Y, and Z.”

Include the higher-level purpose. The purpose statement should also clarify the model’s higher-level purpose: whether it is to develop understanding of the system, or to make specific predictions, etc. Different high-level purposes lead to different model designs. Use the general purposes from the examples of Element 1 we provide below as a guide.

Tie the purpose to the study’s primary results. One way to make this statement of model purpose specific enough is to explicitly consider what point you are trying to demonstrate with the model. The statement should allow the readers to clearly judge the extent to which the model is successful. This is closely related to the primary analysis you will conduct with the model. Think about the key graph(s) you will produce in your “Results” section, where you apply the model to your main research question. The model’s purpose should include producing the relationship shown in this graph.

Define your terms. If you state that your model’s purpose is (for example) to “predict how the vulnerability of a community to flooding depends on public policy”, you still have not stated a clear model purpose. The term “vulnerability to flooding” could mean many things: drowning, travel delays, property damage, etc.; and “public policy” could refer to zoning, insurance, or emergency response. Be clear about exactly what inputs and results your model addresses.

Be specific to this version of the model. To keep the description clear and focused, do not discuss potential future modifications of the model to new purposes or patterns. (Future plans might be described instead in the Discussion section of a publication.) However, if the same model is designed for multiple purposes, those purposes should be described even if they are not addressed in the current publication.

Do not describe the model yet. Authors are often tempted to start describing how the model works here in the purpose statement, which is a mistake. Instead, address only the purpose here and then, in subsequent sections, you can tie the model’s design to the purpose by explaining why specific design decisions were necessary for the model’s purpose.

Make this purpose statement independent. Model descriptions are typically published in research articles or reports that also include, in their introduction, a statement of the study’s purpose. This ODD element should be independent of any presentation of study purpose elsewhere in the same document, for several reasons: (a) an ODD description should always be complete and understandable by itself, and (b) re-stating the model purpose as specifically as possible always helps modelers (and readers) clarify what should be in the model.

Use qualitative but testable patterns. Patterns useful for designing and evaluating ABMs are often general (observed at multiple locations or times) and qualitative. However, using patterns to evaluate a model requires that they be testable: you need a reproducible way to determine whether the model matches the pattern. Making patterns testable can be as simple as stating them as qualitative trends, e.g., that output X increases as variable A decreases. We generally discourage statistical definitions of patterns where the pattern is, in fact, qualitative. There are more appropriate ways of formalizing qualitative patterns, e.g. Thorngate and Edmonds (2013).

Document the patterns. A complete description of the patterns used in modeling needs to document why the patterns were selected: what evidence supports them, and what is their role in justifying the purpose? Documenting patterns can range from simply stating them as widespread (or your own) beliefs, to citing multiple empirical studies that observed each pattern. Thorough documentation of several patterns can require substantial text, which could conflict with keeping this “Overview” part of ODD short. In this case, patterns can be thoroughly documented in a separate section of a report or article and summarized in the ODD description; thorough documentation of the patterns in the ODD description is not essential for it to be complete enough to make the model reproducible.

Checklist

The ODD text for this element should describe:

• The model’s specific purpose(s).
• The patterns used as criteria for evaluating the model’s suitability for its purpose.

Element 1 examples

Purpose statements Pattern descriptions

2. Entities, state variables, and scales

This ODD element describes the things represented in the model. (Such a description can also be called an “ontology”.)

It includes three closely related parts.

The first part describes the model’s entities. An entity is a distinct or separate object or actor that behaves as a unit. ABMs typically have several kinds of entities and one or more entities of each kind. Here, describe the kinds of entities: what the entities represent, why they are in the model, and whether the model has one, several, or many entities of each kind.

The following types of entities are typical:

• Spatial units such as grid cells or GIS polygons. In spatially explicit models, these entities represent variation in conditions over space. Some models represent agent “locations” in non-geographic spaces, including networks.
• Agents or individuals. An ABM can have one or several types of agents that should each be described separately.
• Collectives (as described in Element 4, below). If the model includes agent collectives that are represented as having their own variables and behaviors, then they are also entities to describe.
• Environment. Many models include a single entity that performs functions such as describing the environment experienced by other entities and keeping track of simulated time. Such an entity can be referred to as the environment, or by using the terms used by modeling platforms for the software object that performs these functions (e.g., the “Observer” in NetLogo (Wilensky 1999), the “model”, “model swarm”, etc., in other platforms).
  • Even if this entity does not represent anything specific in the modeled system, it can be included in ODD if useful for describing the model.
  • Any global variables essential to the model, such as those describing the environment, should be associated with such an entity.

The second part of this element is a description of the state variables (sometimes called “attributes”) of each kind of entity.

State variables of an entity are variables that characterize its current state; a state variable either

• distinguishes an entity from other entities of the same kind (i.e., different entities or agents have different values of the same variable), or
• traces how the entity changes over time (the value of an entity’s variable changes over simulated time).

For example, sex is an agent state variable if there are male and female agents, but not if, as in some ecological models, only females are included; in that case, sex cannot be used to distinguish agents because they all have the same sex.

Example agent state variables are weight, sex, age, information known, memory of a specific variable or type of event, wealth, social rank, location (defined by spatial coordinates or by which grid cell or network node the entity occupies), which of several categories of agent it is in (e.g., buyer or seller in a market model where agents can switch roles), and which behavioral strategies the agent is currently using. Example variables of the environment are temperature, immigration rate, or disturbance frequency (ecology), or market price or flooding risk (social sciences).

In addition to simply listing each kind of entity’s state variables, an ODD description should also describe the characteristics of each variable. These characteristics include:

• What exactly does the variable represent (including its units if it has units)?
• Is the variable dynamic (changing over time) or static (never changing in time)?
• Type: is the variable an integer, a floating-point number, a text string, a set of coordinates, a boolean (true/false) value, a probability?
• Range: can the variable have only a few discrete values (e.g., a text string representing the season with values of “spring”, “summer”, “fall”, or “winter”), is it a number with limited range (e.g., a size variable that cannot be negative), or can it have any value?

It is usually convenient to list each kind of entity’s state variables and their characteristics in a table.

The third part of this element is describing the model’s spatial and temporal scales.

By “scales” we mean the model’s extent—the total amount of space and time represented in a simulation— and resolution—the shape and size of the spatial units and the length of time steps.

It is important to specify what the model’s spatial units and time steps represent in reality. A simple example description of scales is: “One time step represents one year and simulations were run for 100 years. Each square grid cell represents 1 ha and the model landscape represents 1,000 x 1,000 ha; i.e., 10,000 square kilometers”. Models often use different time scales for different processes, or processes that are triggered only under certain conditions; such variations in scales should be described here.

Guidance

Provide the rationale for the choice of entities. Choosing which kinds of entities to include in a model, and which to leave out, is a very fundamental and important design decision. Often this choice is not straightforward: different models of the same system and problem may contain different entities. Therefore, it is important for making your model scientific instead of arbitrary to explain why you chose its entities. (Pattern-oriented modeling, discussed at Element 1, is a strategy for making this choice.)

Include networks and collectives as entities if they have their own state variables and behaviors. As discussed under ODD Element 4, ABMs can represent networks or other collectives as either (1) entities with their own state variables and behaviors or (2) emergent properties of other agents (e.g., flocks of birds that form as a result of how the birds move). Collectives of the first type should be described in this ODD element, while those of the second type should not. Do not include networks as model entities if they exist only as links among agents or can otherwise be completely described by the characteristics of their members.

Do not confuse parameters with state variables. Parameters are coefficients or constants used in model equations and algorithms. ODD authors often mistakenly include parameters in their description of state variables. Be careful to include as state variables only those meeting the criteria stated above: they define how an entity’s state varies over time or how state varies among entities of the same type. By these criteria, the variables of a unique entity (there is only one entity of its kind, e.g., the Observer or the global environment) are state variables if they vary over time and parameters if they are static. (Models can be designed so that some parameter values vary among entities. For example, each agent may draw its own value of some parameter from a random distribution, to represent individual variation in a process. Such parameters with values that vary among entities should be treated as state variables.)

Do not include all of an entity’s variables as state variables. The list of state variables should rarely include all the entity’s variables in the computer code. State variables should be “low level” in the sense that they cannot be calculated from other state variables; do not include variables that are readily calculated from other variables. For example, if farms are represented by grid cells, the distance from a farm to a certain service center would not be a state variable because it can be calculated from the farm’s and service center’s locations. Also do not include variables that are only used in a particular computer implementation instead of being essential to the model; display variables are an example. One way to define state variables is: if you want (as modelers often do) to stop the model and save it in its current state, so it can be re-started in exactly the same state, what is the minimum information you must save? Those essential characteristics of each kind of entity are its state variables.

Do not yet describe when or why state variables change or what entities do. This element of ODD is simply to describe what is in the model, not what those things do. Save all discussion of what happens during simulations for later elements.

Describe whether the model represents space, and how. Not all ABMs are spatial; some do not represent space or the location of agents. The discussion of spatial scales should therefore start by saying whether space is represented. This discussion should also say how space is represented. First, state whether the model is one-, two-, or three-dimensional. Many ABMs are two-dimensional and represent space as a collection of discrete units (“cells” or “patches”), so the location of an agent is defined by which spatial unit it is in. These units are often square grid cells, but it is also common to use hexagonal cells and irregular polygons. Space can also be represented as continuous, with locations described using real numbers. Both discrete and continuous space can be used in the same model. The NetLogo platform, for example, uses a discrete square grid for spatial variables but allows agent locations to use continuous space. You therefore need to define which of these possibilities are used in your model.

If a model uses toroidal space, the description of spatial scales needs to say so. “Toroidal space” (in NetLogo, “world wrapping”) approximates an infinite space by assuming that opposite sides of a rectangular model extent are connected to each other. (In physics, toroidal space is also often referred to as “periodic boundary conditions.”) An agent can move east off the right edge of the space, for example, and appear at the western edge.

Describe whether the model represents time, and how. While not all models include a temporal dimension, almost all ABMs do. You therefore need to describe how time is represented. Most ABMs represent time via discrete time steps: time is assumed to jump ahead one step at a time and all model processes represent what happens during these jumps. However, some models also represent some processes as occurring in continuous time: events can be executed at specific, unique times. An ODD description needs to say whether the model uses time steps and how long these steps are, and also identify any processes that are instead modeled using continuous time. (How processes use continuous time should be summarized in Element 3, with full detail in Element 7.)

Describe whether the model represents any dimensions other than time and space. It is possible for ABMs to use dimensions other than physical ones. For example, human agents could be represented as inhabiting a two-dimensional space with socioeconomic status on one axis and age on the second. If any such alternative dimensions are used, describe them as you would space.

For abstract models without specific scales, provide an approximation or conceptual definition of scales. Some ABMs are not built to represent a specific real system, so their spatial and temporal scales are not clearly specified. For such models, the ODD description should at least describe what the time steps and spatial units represent conceptually and approximate their scale. For example, the well-known Schelling segregation model represents households that move when unhappy but most implementations (e.g., “Segregation” in NetLogo’s models library) do not specify its scales. But assuming that households occupy urban houses and that moving takes several months lets us approximate the spatial scale—grid cells are urban lots—and the time step length—time steps are the time it takes a family to sell one house and buy another.

When spatial or temporal scales are not fixed, describe typical values. Some models are designed for application to multiple systems that can vary in spatial resolution or extent, and for simulation experiments that vary in duration. In these cases, the spatial and temporal scales differ among applications so cannot be stated exactly. In such cases, the ODD description should state which scales are fixed vs. variable, and provide the range of typical values for the scales that vary.

Provide the rationales for spatial and temporal scales. In any kind of modeling, choosing the scales is well-known as a critical design decision because model scales can have effects that are strong yet difficult to identify. This is an especially important part of your model to justify, and pattern-oriented modeling is again one strategy for doing so.

Describe scales in a separate paragraph. While it can be straightforward to describe spatial scales while describing the model’s spatial entities (e.g., “Space is represented as a 100 by 100 grid of square cells that each represent 1 cm2 ”), we recommend writing a separate paragraph that concisely states the spatial and temporal scales. These are fundamental characteristics of a model that readers will often want to find easily.

Do not discuss model processes and behaviors. While identifying the entities and their state variables here, it is tempting to also describe how they are initialized and the processes that cause them to change. However, those topics are instead described in elements 3 and 5.

Checklist

Describe:

• The kinds of entities in the model and what they represent.
• Why those entities were included and, if relevant, why other entities were not included.
• The state variables of each kind of entity, usually in a table. For each state variable, describe exactly what it represents, its units, whether it is dynamic or static, its type, and its range.
• Whether the model represents time and, if so, whether time is represented via discrete time steps, as continuous, or both. If time steps are used, define their length (the temporal resolution). Describe how much time is represented in a simulation (the temporal extent).
• Whether the model represents space and, if so, whether space is represented as discrete spatial units, as continuous, or as both. If discrete spatial units are used, describe their shape and size (the spatial resolution). Describe how much total space is represented (the spatial extent).
• Whether any other dimensions are represented, and how.
• Why the spatial and temporal scales were chosen.

3. Process overview and scheduling

The main purpose of this element is to provide a summary overview of what the model does as it executes: what processes are executed, in what order. (The details of these processes, except for very simple ones, are fully described in Element 7.)

At the same time, the element describes the model’s scheduling—the order in which the processes are executed—in complete detail.

A model’s schedule specifies the order in which it executes each process, on each time step. We recommend describing the schedule here as a list of what simulation modelers call “actions”. An action specifies

1) which entity or entities 2) execute which process or behavior that 3) changes which state variables, and 4) the order in which the entities execute the process.

The processes and behaviors, unless extremely simple, should be described only as executing a specific submodel that is fully described in Element 7. (A “submodel” is a part of the model that represents one particular processes; submodels are described independently in Element 7.)

A simple example schedule is:

1. The environment executes its “update” submodel, which updates its state variables date, temperature, rainfall, and the value of the habitat cell state variable food-availability.
2. The agents each execute their “adapt” submodel, in which they choose a new location (update their state variable for which habitat cell they occupy) in response to the new environmental conditions. The agents do this in order of highest to lowest value of their state variable body-weight.
3. The agents execute their “grow and survive” submodel in which they (a) update their body-weight variable by how much they grow, and (b) either live or die. The agents execute this action in an order that is randomized each time step.
4. The display and file output are updated.

However, actions can be hierarchical: one action can include executing other actions. The first action in the above example might actually be made up of two sub-actions:

1. The environment executes its “update” submodel, which includes: a. The environment increments its date variable by 1 day. b. The environment reads in new values of its variables temperature and rainfall from the input data (Element 6). c. The spatial cells each execute their “update food” submodel, which calculates a new value of the cell state variable food-availability from the updated environment variables. The order in which cells execute is arbitrary.

For most ABMs the Process overview and scheduling element should start with a summary of the schedule: a concise list of actions like the above example. The summary is then followed by discussion as necessary to

(1) fully explain any scheduling that does not follow simple time steps, and (2) provide the rationale for the choice of processes in the model and how they are scheduled.

Guidance

Be complete: include everything that is executed each time step. Remember that while this ODD element is intended as an overview of how the model executes, it is the only place in ODD that describes exactly what actions are executed and their order of execution.

Describe the execution order. For any action that is executed by more than one entity (e.g., any action executed by some or all agents or by the spatial units), you must specify the order in which the agents execute. Sometimes the execution order is unimportant, but often it is a very important characteristic of the model.

Make sure the schedule summary says when state variables are updated. The only purpose of the model’s processes and submodels is to update the entity state variables as simulated time proceeds. An essential part of this element is therefore to say exactly when the state variables of each entity are changed. Use the list of state variables in Element 2 as a checklist and make sure this element describes when they are updated. If the agents update a shared variable that affects other agents (e.g., a variable that represents resource availability), say whether the model uses “asynchronous updating”, in which the agents change the variable one at a time as they execute a submodel that uses the variable, or “synchronous updating”, in which the variable is updated only after all agents have executed.

While Element 3 describes what happens each time step, the time step length and temporal extent of simulations should be described only in Element 2.

Provide the rationale for the processes and scheduling, as a separate discussion. This element is the place to explain why you chose to include the processes in the model and to exclude other processes. This is also where to justify why you scheduled the processes as you did: why are the actions in the given order (if it is not completely self-evident), and why did you chose the execution order for the actions executed by multiple entities? (Most commonly, the agents in an ABM execute any particular action in (a) arbitrary order because the action involves no interaction among agents, so order does not matter; (b) randomized order, to avoid artifacts of execution order; or (c) in order of some agent state variable, to represent a hierarchy among agents.) Scheduling can have very strong effects on model results so should be considered carefully. These explanations should be written as paragraphs that come after the schedule summary.

Keep the overview concise. This element is not the place to explain model processes in detail. Actions are typically described simply by saying which submodel is executed, with a cross-reference to the submodel’s complete description in Element 7. Use submodel names that describe what the submodels do. However, extremely simple processes can be fully described here; for example: “All agents increment their state variable agent-age by 1.”

Use diagrams like flow charts if they are helpful for specific actions, but they are rarely sufficient by themselves. Flow charts are the traditional way of describing the execution of some kinds of computer models, and can be helpful for explaining more complicated scheduling of an ABM. However, our experience has been that flow charts rarely can define an ABM’s schedule completely, clearly, and accurately by themselves. Use them if helpful for some particular action, but do not rely on one flow chart or diagram to define a whole model’s schedule; and accompany diagrams with sufficient text to make the process overview and schedule completely clear.

If necessary, use pseudo-code (but not actual program statements) to clarify execution order. ABMs sometimes include complex logic to determine which entities execute which processes when. Pseudo-code—natural language statements that include logic similar to computer code—can be useful for describing such logic. Do not, though, use actual programming statements from the model’s code in ODD; understanding such statements requires the reader to know the programming language.

If your model includes actions scheduled as discrete events in continuous time steps, summarize how those events are scheduled. The above guidance and example schedule apply to models in which all actions are executed on discrete time steps (as discussed for Element 2). If your model also includes actions that are scheduled to execute in continuous time, here you should supplement the process overview and schedule with a list of those actions and say in general how they are scheduled (what causes an event to be scheduled for execution and what determines when it executes). Complete details of how events are scheduled should be provided in the submodel descriptions of Element 7.

Checklist

Provide:

• A complete but concise model schedule that defines exactly what happens each time step. The schedule should be presented as a hierarchy of “actions” that each describe which entity or entities execute which process or submodel, which state variables are updated, and (for actions executed by multiple entities such as all agents or spatial cells) the order in which the entities execute it.
• A separate discussion, if needed, that summarizes how actions executed in continuous time instead of discrete time steps are scheduled.
• A discussion providing the rationale for why the model includes the processes it does.
• A discussion providing the rationale for how the actions are scheduled. Why are the actions executed in the given order? For those actions executed by multiple entities, why did you choose the order in which the entities execute?

4. Design concepts

The Design concepts element describes how 11 concepts that characterize ABMs were implemented in the model.

This element is not needed to describe exactly what the model does or to replicate it, but instead is intended to place the model within a common conceptual framework and to show how its developers thought about its design.

The design concepts are intended to capture important characteristics of ABMs that are not described well by traditional description methods such as equations and flow charts. Traditional modeling literature and training do not address most of these concepts, yet most of them are important for most ABMs. Therefore, the concepts serve as a checklist of important design decisions that should be made consciously and documented. The concepts are also useful as a way to categorize, compare, and review ABMs.

Some of the design concepts—especially Learning and Collectives—are not used in most ABMs, and few models use all the other concepts. For the concepts that your model does not use, provide a simple statement such as “Learning is not implemented” or “The model includes no collectives.”

Occasionally, modelers may identify an important concept underlying the design of their ABM that is not included in the ODD protocol. If such authors are sure that this concept cannot be incorporated in the 11 existing concepts and that it is important to understanding the design of their model, they should give it a short name, clearly announce it as a design concept not included in the ODD protocol, and present it at the end of the Design concepts element.

The Design concepts element is a particularly important place to provide the rationale for model design decisions. Your model will seem much less ad hoc and more scientific if you provide even a short summary of the reasoning and evidence that led to how these concepts were implemented. However, if providing the rationale requires extensive discussion it can be provided in one of the detailed submodel descriptions of Element 7.

For each design concept, we provide a summary of its meaning and provide a checklist of what to describe. The ODD text for this element should be at a conceptual level: instead of providing full detail for how each concept is implemented, provide a general description of its use with (if relevant) citations for literature supporting that use. Use cross-referencing to point readers to the submodel descriptions (Element 7) where full details are described.

Basic principles

This concept relates the model to existing ideas, theories, hypotheses, and modeling approaches, to place the model within its larger context. These principles can occur at both the model level (e.g., does the model address a question that has been addressed with other models and methods?) and at the agent level (e.g., what theory for agent behavior does the model use, and where did this theory come from?). Describing such basic principles makes a model seem more a part of science and not made up without consideration of previous ideas.

Describe:

• The general concepts, theories, hypotheses, or modeling approaches underlying the model’s design, at both the system and agent levels.
• How these basic principles are taken into account. Are they implemented in submodels or is their scope the system level? Is the model designed to provide insights about the basic principles themselves, i.e. their scope, their usefulness in real-world scenarios, validation, or modification?
• Whether the model uses new or existing theory for the agent behaviors from which system dynamics emerge. What literature or concepts are agent behaviors based on?

Emergence

This concept addresses a fundamental characteristic of ABMs: that system behavior can emerge from the behavior of agents and from their environment instead of being imposed by equations or rules. However, the degree to which results are emergent or imposed varies widely among models and among the different kinds of results produced by a model. This concept therefore describes which model results emerge from which mechanisms and which results instead are imposed; here, “model results” not only refers to system level dynamics, but also to the behavior of the agents.

This element should identify which model results emerge from, or are imposed by, which mechanisms and behaviors, but should not address how such mechanisms and behaviors work; that explanation begins with the following concept.

Describe:

• Which key model results or outputs are modeled as emerging from the adaptive decisions and behaviors of agents. These results are expected to vary in complex and perhaps unpredictable ways when particular characteristics of the agents or their environment change.
• For those emergent results, the agent behaviors and characteristics and environment variables that results emerge from.
• The model results that are modeled not as emergent but as relatively imposed by model rules. These results are relatively predictable and independent of agent behavior.
• For the imposed results, the model mechanisms or rules that impose them.
• The rationale for deciding which model results are more vs. less emergent.

Adaptation

This concept identifies the agents’ adaptive behaviors: what decisions agents make, in response to what stimuli.

All such behaviors should be identified and described separately. The description should include components of behavior such as: the alternatives that agents choose among; the internal and environmental variables that affect the decision; and whether the decision is modeled as “direct objective seeking”, in which agents rank alternatives using a measure of how well each would meet some specific objective (addressed in the Objectives concept, below), or as “indirect objective seeking”, in which agents simply follow rules that reproduce observed behaviors (e.g., “go uphill 70% of the time”) that are implicitly assumed to convey success.

Many ABMs include only very simple behaviors that can be hard to think of as adaptive or even as decisions. An example is the Schelling segregation model: in it, agents simply move to a new randomly-selected location when too few of their neighbors are the same color. However, even such simple responses should be described as adaptive behaviors in ODD: the agents decide whether to stay or move by testing whether an objective measure—the percentage of neighbors having their color—is below a threshold value.

At the other extreme are ABMs that use complex evolved behaviors: each agent has an internal decision model such as an artificial neural network that is evolved in the ABM to produce useful adaptive behavior. This approach can still be described in the framework provided here: what alternatives are considered by the decision model, what its inputs are, and how its outputs are used to determine behavior.

An additional step for such models is to also describe the “training conditions”: what problem were the agents given to solve in the evolution of their decision models? Such adaptive behavior models can be considered indirect objective seeking because the agents have been trained via evolution to produce behaviors successful under the training conditions.

Describe, for each adaptive behavior of the agents:

• What decision is made: what about themselves the agents are changing.
• The alternatives that agents choose from.
• The inputs that drive each decision: the internal and environmental variables that affect it.
• Whether the behavior is modeled via direct objective-seeking—evaluating some measure of its objectives for each alternative—or instead via indirect objective-seeking—causing agents to behave in a way assumed to convey success, often because it reproduces observed behaviors.
• If direct objective-seeking is used, how the objective measure is used to select which alternative to execute (e.g., whether the agent chooses the alternative with the highest objective measure value, or the first one that meets a threshold value).

Objectives

This concept applies to adaptive behaviors that use direct objective-seeking; it defines the objective measure used to evaluate decision alternatives. (In economics, the term “utility function” is often used for an objective measure; in ecology, the term “fitness measure” is used.)

If adaptive behaviors are modeled as explicitly acting to increase some measure of the individual’s success at meeting some objective, what is that measure, what does it represent, and how is it calculated? Objective measures are typically estimates of future success that depend on the decision being modeled; they can be thought of as the agent’s internal model of how its objectives will be met by the alternative being considered.

Note that agents that are part of a Collective (defined below) or larger system—members of a team, social insects, leaves of a plant, cells in a tissue—can be modeled as having objectives that serve not themselves but the larger system they belong to.

Describe, for each adaptive behavior modeled as direct objective-seeking:

• What the objective measure represents: what characteristic of agent success does it model? An example from economics is expected wealth at some future time; in an ecological model an organism might use the probability of surviving until a future time or the expected number of future offspring.
• What variables of the agent and its environment drive the objective measure.
• How the measure is calculated. If it is a simple equation or algorithm, it can be described completely here; otherwise, provide a cross-reference to the submodel in Element 7 that describes it completely. Keep in mind that some other design concepts (e.g., Prediction, Sensing) may also describe parts of the objective measure.
• The rationale behind the objective measure: why does it include the variables and processes it does?

Learning

This concept refers to agents that change how they produce adaptive behavior over time as a consequence of their experience.

Learning does not refer to how adaptation depends on state variables that change over time; instead, it refers to how agents change their decision-making methods (the algorithms or perhaps only the parameters of those algorithms) as a consequence of their experience. While memory can be essential to learning, not all adaptive behaviors that use memory also use learning. Few ABMs so far have included learning, even though a great deal of research and theory addresses how humans, organizations, and other organisms learn.

Describe:

• Which adaptive behaviors of agents are modeled in a way that includes learning.
• How learning is represented, especially the extent to which the representation is based on existing learning theory.
• The rationale for including (or, if relevant, excluding) learning in the adaptive behavior, and the rationale for how learning is modeled.

Prediction

Prediction is fundamental to successful decision-making (Budaev et al. 2019) and, often, to modeling adaptation in an ABM. (Railsback and Harvey 2020 extensively discuss the use of simple predictions in modeling difficult decisions by model agents.)

Some ABMs use “explicit prediction”: the agents’ adaptive behaviors or learning are based on explicit estimates of future conditions (future values of both agent and environment state variables) and future consequences of decisions. For these ABMs, explain how agents predict future conditions and decision consequences. What internal models of future conditions or decision consequences do agents use to make predictions for decision-making?

Models that do not include explicit prediction often include “implicit prediction”: hidden or implied assumptions about the future consequences of decisions. A classic example of implicit prediction is that following a gradient of increasing food scent will lead an agent to food.

Describe:

• How the models of adaptive behavior use either explicit or implicit prediction.
• The rationale for how prediction is represented: is the model designed to represent how the agents actually make predictions? Or is prediction modeled as it is simply because it produces useful behavior?

Sensing

This concept addresses what information agents “know” and use in their behaviors. The ability to represent how agents can have limited or only local information is a key characteristic of ABMs.

Here, say which state variables of which entities an agent is assumed to “sense”, and how.

Most often, sensing is modeled by simply assuming that the agent accurately knows the values of some variables, neglecting how the agent gets those values or any uncertainty in their values. But ABMs can model the actual sensing process—how an agent gathers information about its world—when that process is important to the model’s purpose.

And ABMs can represent uncertainty in sensing: you could assume, for example, that your agents base some decision on the sensed value of a neighbor’s variable, when that sensed value includes random noise. (In fact, sensing itself can be modeled as an adaptive behavior: agents can decide how much of their resources to invest to collecting information when more information supports better decisions but is costly to obtain.)

Describing sensing includes stating which variables of which entities are sensed. The description must cover what an agent knows about its own state: we need to say explicitly which of an agent’s own state variables it is assumed able to use in its behavior. When agents sense variables from other entities, such as the spatial unit they occupy or other agents, we must specify exactly how they determine which entities they sense values from. In ABMs, sensing is often assumed to be local, but can happen through networks or can even be assumed to be global.

Describe:

• What state variables, of themselves and other entities, agents are assumed to sense and use in their behaviors. Say exactly what defines or limits the range over which agents can sense information.
• How the agents are assumed to sense each such variable: are they assumed simply to know the value accurately? Or does the model represent the mechanisms of sensing, or uncertainty in sensed values?
• The rationale for sensing assumptions.

Interaction

The ability to represent interaction as local instead of global is another key characteristic of ABMs. This concept addresses which agents interact with each other and how.

We distinguish two very common kinds of interaction among agents: direct and mediated.

• Direct interaction is when one agent identifies one or more other agents and directly affects them, e.g. by trading with them, having some kind of contest with them, or eating them.
• Mediated interaction occurs when one agent affects others indirectly by producing or consuming a shared resource; competition for resources is typically modeled as a mediated interaction.

Communication is an important type of interaction in some ABMs: agents interact by sharing information. Like other kinds of interaction, communication can be either direct or mediated. An example of mediated communication is one insect depositing a pheromone that indicates to other insects that food was found.

Describe:

• The kinds of interaction among agents in the model, including whether each kind is represented as direct or mediated interaction.
• For each kind of interaction, the range (over space, time, a network, etc.) over which agents interact. What determines which agents interact with whom?
• The rationale for how interaction is modeled.

Stochasticity

Here, describe where and how stochastic processes—those driven by pseudorandom numbers—are used in the model.

While some ABMs base most of their processes on random events, others can produce highly variable results with no stochasticity at all.

In general, stochastic processes are used when we want some part of a model to have variation (among entities, over time, etc.) but we do not want to model the mechanisms that cause the variability. It may be critical for a model to include how weather affects some system such as the electric power grid, but we certainly do not want to add the enormous complexity of predicting weather to the model; instead, we simply model the timing and duration of weather events as stochastic processes.

One common use of stochasticity in ABMs is to insert variability in initial conditions: when we create our agents (and other entities) at the start of a simulation (Element 5, below) we do not want them to be identical, so we use pseudorandom number distributions to set the initial values of some state variables.

A second common use is to simplify submodels by assuming they are partly stochastic. Assuming that an agent dies if a random number between 0.0 and 1.0 is greater than its survival probability is a very common example: we do not want to represent all the detail of when agents die.

A third use of stochasticity is modeling agent behaviors in a way that causes the model agents to use different alternatives with the same frequency as real agents have been observed to. For example, a sociological model could use a stochastic process to model the age at which people marry, comparing random numbers to the marriage rates observed in real people. This approach would impose the observed marriage rates on the simulated population.

Describe:

• Which processes are modeled as stochastic, using pseudorandom number distributions to determine the outcome.
• Why stochasticity was used in each such process. Often, the reason is simply to make the process variable without having to model the causes of variability; or the reason could be to make model events or behaviors occur with a specified frequency.

Collectives

Collectives are aggregations of agents that affect, and are affected by, the agents.

They can be an important intermediate level of organization in an ABM; examples include social groups, fish schools and bird flocks, and human networks and organizations.

If the agents in a model can belong to aggregations, and those aggregations have characteristics that are different from those of agents but depend on the agents belonging to them, and the member agents are affected by the characteristics of the aggregations, then the aggregations should be described here as collectives.

Collectives can be modeled in two ways.

First, they can be represented entirely as an emergent property of the agents, such as a flock of birds that assembles as a result of the flight rules given to the simulated birds. In this case, the collectives are not explicitly represented in the model: they do not have state variables or behaviors of their own.

Second (and more common) is representing collectives explicitly as a type of entity in the model that does have state variables and its own behaviors. Social groups of animals or people (dog packs, political parties) have been represented this way.

Describe:

• Any collectives that are in the model.
• Whether the collectives are modeled as emerging entirely from agent behaviors, or instead as explicit entities.
• In overview, how the collectives interact with each other and the agents to drive the behaviors of the entire system. (The details of these interactions will appear in other ODD elements.)

Observation

This concept describes how information from the ABM is collected and analyzed, which can strongly affect what users understand and believe about the model. This concept can also be another place to tie the model design back to the purpose stated in Element 1: once the model is built and running, how is it used to address its purpose?

This concept is not intended to document how simulation experiments and model analyses are conducted, but instead to describe how information is collected from the model for use in such analyses. Observation is important because ABMs can be complex and produce many kinds of output: it is impossible to observe and analyze everything that happens in such a model so we must explain what results we do observe.

Observation almost always includes summary statistics on the state of the agents and, perhaps, other entities such as spatial units and collectives. The ODD description needs to state how such statistics were observed: which state variables of which agents (e.g., were agents categorized?) were observed at what times, and how they were summarized. It is especially important to understand whether analyses considered only measures of central tendency (e.g., mean values of variables across agents) or also observed variability among agents, e.g., by looking at distributions of variable values across all agents.

Modelers sometimes also collect observations at the agent level, e.g., by selecting one or more agents and having them record their state over simulated time. Such observations can be useful for understanding behaviors that emerge in a model.

The ability to legitimately compare simulation results to data collected in the real world can be a major observation concern, leading some modelers to simulate, in their ABM, the data collection methods used in empirical studies. This “virtual scientist” technique (modeling the data collector; Zurell et al. 2010) strives to understand the biases and uncertainties in the empirical data by reproducing them in an ABM where unbiased and accurate observations are also possible.

Describe:

• The key outputs of the model used for analyses and how they were observed from the simulations. Such outputs may be simple and straightforward (e.g., means of agent state variables observed once per simulated week), or fairly complex (e.g., the frequency with which the simulated population went extinct within 100 simulated years, out of 1000 model runs).
• Any “virtual scientist” or other special techniques used to improve comparison of model results to empirical observations.

  5. Initialization

  Elements 5-7 are the “Details” part of ODD: now your goal is to provide complete detail so that your model and its results can be reproduced.

This element describes exactly how the model is initialized: how all its entities are created before the simulations start.

Describing initialization includes specifying how many entities of each kind are created and how their state variables are given their initial values.

Guidance

Describe everything required to set up the model. Initializing state variables usually includes more than just assigning numbers to entities; it can include setting agent locations in spatial models, building networks of agents, and creating any collectives that exist at the start of a simulation. Any actions or submodels that are executed only once, at the start of a simulation, should be considered part of initialization and described here.

Explain whether initialization is intended to be case-specific or generic. If your model is designed to simulate only one particular case or study system, say so. In that case, this ODD element should fully describe the specific initialization data used for that case. If instead your model is designed to be generally applicable to multiple sites, then the Initialization element must be more generic. Instead of describing specific data sources, it can describe the kinds of data and information needed to apply the model to different sites.

Explain whether initialization is always the same or differs among scenarios. Models are used by simulating different scenarios. Scenarios can differ from each other in how the model is initialized (e.g., by simulating different numbers of agents or different environments), or by varying factors such as input data (Element 6) or parameter values that affect results only after simulations start. In the first case, with scenarios differing in initial conditions, then the goal of simulation experiments is to understand the effects of initial conditions. In the second case, the goal is to understand the effects of processes happening after initialization and modelers often try specifically to eliminate effects of initial conditions (e.g., by ignoring results until the model has run long enough for initial conditions to have minimal effect). If it is clear which of these two kinds of scenarios will be used in model analyses, say so. If you vary the initial state of the model as part of simulation experiments, it can be helpful to point out here how you do so: which state variables of which entities are varied among scenarios, and how.

Describe data imported to create the model world. If your model uses (for example) GIS data to define its simulated space, or reads in data used to define the initial agent populations, describe such data here. Describe where the data came from, why it was chosen, and how it was prepared. Discuss any uncertainties and limitations of the data, if relevant. (Be sure to understand the difference between initialization data and the input data that are described in Element 6.)

Do not describe parameters and their values here. Even though the model’s parameter values may be read in at the start of a simulation, doing so is not considered part of initialization in ODD because parameter values are not state variables and typically do not change during a simulation. The only parameters that should be described here are any used in initialization; parameters used in the rest of the model should be described in Element 7 with the submodel that uses them.

Do not describe how new agents or entities are created during a simulation. If your model creates new agents or other entities as it executes, not just at the beginning, describe that creation process as a submodel, not as part of initialization. If the same submodel is used to create agents during initialization and during a simulation, it can be described in Element 7 and cited from this element.

Provide the rationale for initialization methods. Your model becomes more scientific if you can explain such initialization decisions as determining which state variables vary among agents (or other entities) and how. It may be appropriate in this element to present simulation experiments that illustrate the effect of alternative initialization assumptions on model results.

Checklist

Describe:

• What entities are created upon initialization, what determines how many of each are created, and how all their state variables are given initial values.
• How the initial locations of entities are set, if relevant.
• How any initial collectives, networks, or other intermediate structures are created.
• Any site-specific data used to initialize the model: the data types, their sources, how they were processed, any known biases or uncertainties, and how they were used in initialization.
• Whether simulation experiments will typically use scenarios that differ in initialization methods; if so, say how initialization will vary.
• The rationale for key initialization methods. For example, explain why initial agents vary among each other in the way they do.

  6. Input data

  Model dynamics are often driven in part by input data, meaning time series of either variable values or events that describe the environment or otherwise affect simulations.

“Driven” means that model state variables or processes are affected by the input, but the variables or events represented by the input are not affected by the model.

One common use of input data is to represent environment variables that change over time. For example, rainfall input may affect the soil moisture variable of grid cells and, therefore, how the recruitment and growth of model trees change. Geographic or other data can be read in periodically to simulate changes in landscapes or other model “spaces”. Often, the input data are values observed in reality (e.g., from a weather station or stock market records) so that their statistical qualities (mean, variability, temporal autocorrelation, etc.) are realistic.

Alternatively, external models can be used to generate input; output from general circulation models is often used to create input “data” representing climate change scenarios, and land use change.

Input data can also describe external events that affect the model during a simulation. Examples include input specifying the times at which new agents are created to represent immigration and the times at which shock events happen.

To make an ABM reproducible, we need to define any input data that drive it. To reproduce specific model results, we need to provide the input data (see Laatabi et al. 2018 for details); and to fully justify the results we need to explain where the data came from and document their uncertainties, biases, and other limitations. Even when we are not trying to make a specific set of model results reproducible, we need to state what input data drive the model. Explaining exactly what the input represents and what sources provide useful values can be important for avoiding misuse of a model.

Guidance

If the model does not use input data, simply say so. In such cases, the ODD description should say “The model does not use input data to represent time-varying processes.”

Input data do not include parameter values or data used to initialize the model. This element does not describe all “data” read by the computer when a simulation starts. Instead, it should only describe input used as the model executes to represent change over time in some particular state variable(s).

Define the input data completely. Say exactly what each input variable represents, provide its units, and describe how the input was or can be obtained. If any methods are used to manipulate data from common sources into the format used by the model, describe them. If relevant, describe uncertainties, biases, or other limitations of the data.

If your ABM is intended to represent multiple scenarios that use different input data, describe the kind of input it needs. If an ABM will be used for different sites or times, so that you cannot anticipate exactly what input data will be used with it, describe exactly what kind of input it needs.

If input was generated from another model, document how. It should not be necessary to completely describe in the ODD how input was generated by another model, if that other model has been published. However, if a “custom” model run was used to create input just for your model, then the methods need to be described either here, in another part of the same publication, or in another document that can be cited here.

Checklist

Describe:

• Whether the model uses any input data to represent variables that change over time or events that occur during a simulation.
• The input data: what it represents, its units, and its source.
• Any nontrivial methods used to collect or prepare the input.
• If input is from another model, how that model was used to generate the input.

  7. Submodels

  This element is where we fully describe any submodels that were cited but not fully described in Element 3 or Element 5.

Element 7 should include a subsection for each such submodel.

Guidance

Describe each submodel completely. The primary concern with Element 7 is being complete: fully describing each submodel’s equations, algorithms, parameters, and parameter values. Tables are often used to define parameters in one place; they should include each parameter’s name, meaning, units, type, default value, range of values analyzed in the model, and information about where the values came from, e.g. literature, unpublished data, experiments, expert opinions, etc. Figures can complement the verbal description of the submodels.

Readers should be able to exactly reproduce each submodel from the ODD description. (It is a good exercise to re-implement key submodels from the ODD description in a spreadsheet or similar platform, and then use that independent implementation to explore and calibrate the submodel as discussed below, to verify that the ODD description is complete, and to test the model software.)

If helpful, break submodels into sub-submodels. Submodel descriptions can be hierarchical: complex submodels are often best described as a set of sub-submodels that are each described separately. Some submodels may even justify a full ODD description of their own (“Nested ODD”, see main text and Supplement S4).

Provide the rationale for submodel design. For any process in a model, there are undoubtedly many possible submodel designs. Explaining how you arrived at your submodel design—by searching the literature, applying theory, fitting statistical relations to data, exploring alternative approaches, etc.—is very important for developing confidence in the full model.

Include analyses of submodels. A second way to develop confidence in submodels and the full ABM is to analyze submodels and show how they behave over all conditions that could occur during simulations. It is very common for ABMs to produce questionable output because their submodels produce unexpected results in some situations, and very difficult to understand such problems when examining the full model. It is also usually very difficult to calibrate a submodel by analyzing results of the full ABM. The way to avoid such problems is to fully implement, calibrate, test, and explore each submodel before putting it in the full ABM. These analyses should be documented in the ODD: do not just describe the submodels but show how they were calibrated and tested, and show (usually via graphs) what results they produce over all the conditions they could encounter in simulations. In addition to inspiring confidence in readers, these analyses invariably save the modeler time by identifying problems earlier. (Note that if your ODD is part of a TRACE document, these analyses would be presented in a different section of the TRACE document; see Supplement S7.)

Checklist

Describe:

• All of the submodels, in a separate subsection for each.
• For each submodel, its equations, algorithms, parameters, and how parameter values were selected.
• The analyses used to test, calibrate, and understand submodels by themselves.

Examples

1. Purpose and patterns

Example statements of model purpose

These examples are organized by the seven general model purposes identified by Edmonds et al. (2019. Different modelling purposes. Journal of Artificial Societies and Social Simulation 22:6; http://jasss.soc.surrey.ac.uk/22/3/6.html). The definitions of these purposes is quoted from Edmonds et al. (This does not list all possible purposes but includes the relevant kinds for the vast majority of academic model published.)

Example purpose of prediction

(“to reliably anticipate well-defined aspects of data that is not currently known to a useful degree of accuracy via computations using the model”):

[Carter N, Levin SA, Barlow A, Grimm V. 2015. Modeling tiger population and territory dynamics using an agent-based approach. Ecological Modelling 312: 347-362]

The proximate purpose of the model is to predict the dynamics of the number, location, and size of tiger territories in response to habitat quality and tiger density… The ultimate purpose of the model, which will be presented in follow-up work, is to explore human-tiger interactions.

Example purpose of explanation (“establishing a possible causal chain from a set-up to its consequences in terms of the mechanisms in a simulation”):

[The Simplified Fish Cannibalism Model; unpublished description by SF Railsback of a model based on that of: DeAngelis DL, Cox DK, and Coutant CC. 1980. Cannibalism and size dispersal in young-of-the-year largemouth bass: experiment and model. Ecological Modelling 8:133-48.]

The purpose of this model is to illustrate a potential explanation for how small changes in the initial size distribution and growth of a cohort of cannibalistic fish can produce large differences in later size distribution, an example of how positive feedback can cause rapid divergence within a system. The mechanism driving the potential explanation is interaction among slow growth from feeding on invertebrates, rapid growth from cannibalism, and “gape limitation” which allows one fish to eat another only if the two fish are sufficiently different in size.

Example purpose of description

(“to partially represent what is important of a specific observed case (or small set of closely related cases)”):

[Arfaoui N, Brouillat E, Saint Jean M. 2014. Policy design and technological substitution: Investigating the REACH regulation in an agent-based model. Ecological Economics 107: 347-365]

The purpose of our model is to understand how different configurations in the policy design of REACH affect the dynamics of eco-innovation and shape market selection and innovation. In our model we take into account supplier–user interactions because they represent an essential element in the development of new technologies, particularly in the chemical industry. Additionally, some stylized facts that illustrate the competition between organic solvents and biosolvents in the surface treatment activity are considered. The objective is to examine to which extent different combinations of flexible and stringent instruments of REACH can lead to the development and diffusion of alternative solvents (biosolvents).

Example purpose of theoretical exposition

(“establishing then characterising (or assessing) hypotheses about the general behaviour of a set of mechanisms (using a simulation)”):

[Polhill JG, Parker D, Brown D, Grimm V. 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: 3]

… SLUDGE is an abstract model designed for theoretical exploration and hypothesis generation. Specifically, SLUDGE was designed to extend existing analytical microeconomic theory to examine relationships between externalities, market mechanisms, and the efficiency of free-market land use patterns.

[Kahl CH, Hansen H. 2015. Simulating creativity from a systems perspective: CRESY. Journal of Artificial Societies and Social Simulation 18: 4]

CRESY simulates creativity as an emergent phenomenon resulting from variation, selection and retention processes (Csikszentmihalyi 1988, 1999; Ford & Kuenzi 2007; Kahl 2009; Rigney 2001). In particular, it demonstrates the effects creators and evaluators have on emerging artifact domains. It was built based on stylized facts from the domain of creativity research in psychology in order to reflect common research practice there (Figure 3). . An abstract model, CRESY was specifically designed for theoretical exploration and hypotheses generation (Dörner 1994; Esser & Troitzsch 1991; Ostrom 1988; Troitzsch 2013; Ueckert 1983; Witte 1991). It constitutes a form of research called theory-based exploration, in which models, concepts, stylized facts and observations are used as input to build a tentative model explored via computer simulation particularly in order to generate new hypotheses and recommendations as output (Bortz & Döring 2002, Ch. 6; Kahl 2012, Ch. 4; Sugden 2000). In contrast to explanatory research, the objective of exploratory research is to build theory instead of testing it. In relating this method to the model’s target, Sternberg (2006) noted creativity research is currently advancing not via its answers, but via its questions.

Example purpose of illustration

(“to communicate or make clear an idea, theory or explanation”):

[Cardona A. 2013. Closing the group or the market? The two sides of Weber’s concept of closure and their relevance for the study of intergroup inequality. SFB 882 Working Paper Series, No. 15: From Heterogeneities to Inequalities. DFG Research Center (SFB), Bielefeld, Germany]

The purpose of the model is to illustrate how individual competition, group closure, and market closure individually or in combination are causally sufficient to produce intergroup inequality. The model does not attempt to realistically replicate any empirically observable system, but instead aims at revealing the distinct causal paths by which each of these processes affect the distribution of resources among groups.

Example purpose of analogy

(“when processes illustrated by a simulation are used as a way of thinking about something in an informal manner”):

[Railsback SF and Grimm VG. 2017. Unpublished description of the culture dissemination model of: Axelrod R. 1997. The dissemination of culture: a model with local convergence and global polarization. Journal of Conflict Research 41: 203-226.]

The model’s purpose is stated [by Axelrod 1997] as being “to show the consequences of a few simple assumptions about how people (or groups) are influenced by those around them.” These assumptions are about how people learn culture from each other and, therefore, how culture spreads and how societies influence each others’ culture. In particular, the model assumes that people or societies share culture locally, and share more with others that are more similar to themselves.

Example purpose of social learning

(“to encapsulate a shared understanding (or set of understandings) of a group of people” developed during a collaborative model-building process):

[Dumrongrojwatthana P, Le Page C, Gajaseni N, Trébuil G. 2011. Co-constructing an agent-based model to mediate land use conflict between herders and foresters in Northern Thailand. Journal of Land Use Science 6: 101-120]

This model was used for improving the researchers understanding on vegetation dynamics in relation to cattle management and reforestation effort, and facilitating the communication among village herders and NKU foresters through scenarios exploration. Moreover, stakeholders’ interactions and decisions making during G&S sessions will be observed and used for further building an ABM.

Example descriptions of patterns

The “patterns” part of Element 1 is new in this version of ODD. Therefore, only a few ODD documents include it.

[Model of vertical migration by Daphnia. Section 5.5 of: Railsback, S. F. and B. C. Harvey. 2020. Modeling populations of adaptive individuals. Princeton University Press, Princeton, New Jersey.]

The purpose of this model is to explain and understand diurnal vertical migration (VM) in zooplankton and how it interacts with a life history tradeoff, the allocation of mass to reproduction or growth. The model is based explicitly on the cladoceran Daphnia magna (which we refer to simply as Daphnia). We evaluate our model by its ability to reproduce three patterns. The first two are of primary importance because they were observed in extensive laboratory experiments by Loose and Dawidowicz (1994) and appear driven directly by the risk-growth tradeoff (Figure 5.1)… Pattern 1: Response of VM to predation risk. This pattern reflects how daphnia VM in the laboratory changed as the perceived risk of predation by fish increased. In the laboratory experiments, perceived risk was increased by adding fish kairomones—chemicals produced by fish that daphnia can use to sense fish density—and perceived risk was quantified as fish concentration (fish/L). With no perceived risk, daphnia stayed near the surface throughout the diurnal cycle. At low fish concentrations, daphnia remained near the surface or migrated only to shallow depths. With high risk, daphnia stayed near the bottom. But at intermediate risk, daphnia exhibited VM, with their mean elevation in the water column low during the day and rising toward the surface at night. And at the lowest fish concentration producing VM, daphnia did not begin migration until growing to a threshold body size. Pattern 2. Selection of slightly shallower depths with low food. Under high perceived risk of fish predation, a decrease in food availability resulted in daphnia selecting shallower depths. However, this change in elevation was small and occurred only in daytime. Pattern 3. Response of reproductive allocation to predation risk. Under low or absent perceived fish predation risk, the daphnia in Fiksen’s model initially allocated almost all their assimilated mass to growth instead of reproduction. This allocation let them reach maximum size quickly and switch to high reproductive output. At higher risk, the daphnia allocated some mass to reproduction from the start, producing some offspring before reaching maximum size. However, at very high risk the daphnia fed very little, grew slowly, and allocated only a moderate fraction of mass to reproduction…

An example of patterns used to develop and test theory for adaptive behavior of agents:

[Woodhoopoe Model from Chapter 19 of: Railsback SF, Grimm V. 2019. Agent-based and Individual-based Modeling: A Practical Introduction, Second Edition. Princeton University Press, Princeton, N.J.]

We also provide three patterns that a theory for scouting forays should cause the ABM to reproduce… The first pattern is the characteristic group size distribution explained in figure 19.2. The second pattern is simply that the mean age of adult birds undertaking scouting forays is lower than the mean age of all subordinates, averaged over the entire simulation. The third pattern is that the number of forays per month is lowest in the months just before, during, and after breeding, which happens in December.

[Caption of Figure 19.2, which explains the first pattern] Characteristic woodhoopoe group size distribution… The histogram shows how many social groups there are (y-axis) for each number of birds per group (x-axis)… The number of groups with zero adults (first bar) is very low, often zero. The number of groups with only 1 adult (second bar) is low, and the numbers of groups with 2–4 adults are highest. As the number of adults increases above 4, the number of groups becomes rapidly smaller…

An example abstract model based only on simple, general patterns:

[Telemarketer Model from Chapter 13 of: Railsback SF, Grimm V. 2019. Agent-based and Individual-based Modeling: A Practical Introduction, Second Edition. Princeton University Press, Princeton, N.J.]

The real purpose of this model is to illustrate several kinds of interactions: how to model them and what their effects are on system behavior. While the model system is imaginary and none too serious, it does represent a common ABM scenario; a system of agents that compete for a resource and grow or fail as a result. For such a model, we define only simple, general patterns as the criteria for its usefulness: [that] two measures of system performance—the changes over time in the number of telemarketers in business and the median time that telemarketers stay in business—depend on how many agents there are and how they interact.

2. Entities, state variables, and scales

We provide separate example descriptions of entities, state variables, and scales.

Example description of entities

[Knoeri C, Nikolic I, Althaus HJ, Binder CR. 2014. Enhancing recycling of construction materials: An agent based model with empirically based decision parameters. Journal of Artificial Societies and Social Simulation 17(3)]

The following entities are included in the model: agents representing construction stakeholders (i.e. awarding authorities, engineers, architects and contractors), projects, grid cells (i.e. virtual geographical location) and the global environment representing the construction market (i.e. construction investments and materials available). Awarding authorities represent private persons, companies, or public authorities awarding prime building contracts, for different purposes (e.g. personal use, economic reasons, public building requirements). Engineers represent the actors responsible for the static design of the concrete structure in buildings; architects the stakeholders designing and supervising the construction, and contractors the companies providing the concrete work… In total, 5788 agents are implemented, representing the statistical distribution of construction stakeholders in the case study. Projects represent the individual construction projects on which these agents interact… Per year about 450 projects are executed. Grid cells represent virtual construction sites of 30×30m… The observer or global environment (i.e. construction market) is the only entity on the system level, defining the annual construction investments and the potential recycling aggregates supply.

Example description of state variables

An example describing state variables in tables. (This example uses the term “observer” for the entity that represents the global environment. The table of observer variables is therefore a table of the variables that represent the environment.):

[Railsback SF, Harvey BC, Ayllón D. InSTREAM 7 Model Description. Unpublished report.]

The observer is a single entity that controls the global variables and submodels. Observer state variables (Table 1) are global variables that change over time. (Static observer variables—those that do not change over simulated time—are considered parameters and are defined with the submodels they are used in.) Table 1: Observer state variables

References Cited

Budaev, S., C. Jørgensen, M. Mangel, S. Eliassen and J. Giske. 2019. Modeling decision-making from the animal perspective: Bridging ecology and subjective cognition. Frontiers in Ecology and Evolution 7:164. doi: 10.3389/fevo.2019.00164

Grimm, V. and S. F. Railsback. 2005. Individual-based modeling and ecology. Princeton University Press, Princeton, New Jersey.

Grimm, V., U. Berger, F. Bastiansen, S. Eliassen, V. Ginot, J. Giske, J. Goss-Custard, T. Grand, S. Heinz, G. Huse, A. Huth, J. U. Jepsen, C. Jørgensen, W. M. Mooij, B. Müller, G. Pe’er, C. Piou, S. F. Railsback, A. M. Robbins, M. M. Robbins, E. Rossmanith, N. Rüger, E. Strand, S. Souissi, R. A. Stillman, R. Vabø, U. Visser, and D. L. DeAngelis. 2006. A standard protocol for describing individual-based and agent-based models. Ecological Modelling 198:115-296. doi:10.1016/j.ecolmodel.2006.04.023

Grimm, V., U. Berger, D. L. DeAngelis, J. G. Polhill, J. Giske, and S. F. Railsback. 2010. The ODD protocol: a review and first update. Ecological Modelling 221:2760-2768. doi:10.1016/j.ecolmodel.2010.08.019.

Laatabi, A., Marilleau, N., Nguyen-Huu, T., Hbid, H., and Babram, M. A. (2018). ODD+ 2D: an ODD based protocol for mapping data to empirical ABMs. Journal of Artificial Societies and Social Simulation 21(2).

Railsback, S. F. 2001. Concepts from complex adaptive systems as a framework for individual-based modelling. Ecological Modelling 139:47-62. doi:10.1016/S0304-3800(01)00228-9

Railsback, S. F. and V. Grimm. 2019. Agent-based and individual-based modeling: a practical introduction, 2nd edition. Princeton University Press, Princeton, New Jersey.