System Dynamics Guide

NetLogo 5.3 User Manual   

This guide has three parts:

What is the NetLogo System Dynamics Modeler?

System Dynamics is a type of modeling where you try to understand how things relate to one another. It is a little different from the agent-based approach we normally use in NetLogo models.

With the agent-based approach we usually use in NetLogo, you program the behavior of individual agents and watch what emerges from their interaction. In a model of Wolf-Sheep Predation, for example, you provide rules for how wolves, sheep and grass interact with each other. When you run the simulation, you watch the emergent aggregate-level behavior: for example, how the populations of wolves and sheep change over time.

With the System Dynamics Modeler, you don't program the behavior of individual agents. Instead, you program how populations of agents behave as a whole. For example, using System Dynamics to model Wolf-Sheep Predation, you specify how the total number of sheep would change as the total number of wolves goes up or down, and vice versa. You then run the simulation to see how both populations change over time.

The System Dynamics Modeler allows you to draw a diagram that defines these populations, or "stocks", and how they affect each other. The Modeler reads your diagram and generates the appropriate NetLogo code -- global variables, procedures and reporters -- to run your System Dynamics model inside of NetLogo.

Basic Concepts

A System Dynamics diagram is made of four kinds of elements: Stocks, Variables, Flows and Links.

A Stock is a collection of stuff, an aggregate. For example, a Stock can represent a population of sheep, the water in a lake, or the number of widgets in a factory.

A Flow brings things into, or out of a Stock. Flows look like pipes with a faucet because the faucet controls how much stuff passes through the pipe.

A Variable is a value used in the diagram. It can be an equation that depends on other Variables, or it can be a constant.

A Link makes a value from one part of the diagram available to another. A link transmits a number from a Variable or a Stock into a Stock or a Flow.

The System Dynamics Modeler figures out how the value of your Stocks change over time by estimating them over and over. The estimation isn't always perfect, but you can affect its accuracy by changing the value of dt. As dt decreases, you estimate the model more frequently, so it gets more accurate. However, decreasing dt also makes the model slower.

Sample Models

There are four basic models in the Sample Models section of the NetLogo Models Library that demonstrate the use of the System Dynamics Modeler. All four basic models explore population growth (and, in models with predation, population decline).

Exponential Growth and Logistic Growth are simple examples of growth in one stock.

Wolf Sheep Predation (System Dynamics) is an example of a system with multiple stocks influencing one another. It models a predator-prey ecosystem using the System Dynamics Modeler.

Wolf Sheep Predation (Docked Hybrid) is an example of a model that runs both the a System Dynamics model and an agent-based model side-by-side. It runs the System Dynamics implementation of Wolf-Sheep Predation next to the agent-based Wolf Sheep Predation model from the Biology section of Sample Models.

How it Works

To open the System Dynamics Modeler, choose the System Dynamics Modeler item in the Tools menu. The System Dynamics Modeler window will appear.

screen shot

Diagram Tab

The Diagram tab is where you draw your System Dynamics diagram.

The toolbar contains buttons to edit, delete and create items in your diagram.

Creating Diagram Elements

screen shot

A System Dynamics diagram is made up of four kinds of components: Stocks, Variables, Flows and Links.

Stock

To create a Stock, press the Stock button in the toolbar and click in the diagram area below. A new Stock appears. Each Stock requires a unique name, which becomes a global variable. Stocks also require an Initial value. It can be a number, a variable, a complex NetLogo expression, or a call to a NetLogo reporter.

Variable

To create a Variable, press the Variable button and click on the diagram. Each Variable in the System Dynamics Model requires a unique name, which becomes the name of a procedure, or a global variable. Variables also require an Expression. This expression can be a number, a variable, a complex NetLogo expression, or a call to a NetLogo reporter.

Flow

To create a Flow, press the Flow button. Click and hold where you want the Flow to begin -- either on a Stock or in an empty area -- and drag the mouse to where you want the Flow to end -- on a Stock or in an empty area. Each Flow requires a unique name, which becomes a NetLogo reporter. Flows require an Expression, which is the rate of flow from the input to the output. This expression can be a number, a variable, a complex NetLogo expression, or a call to a NetLogo reporter. If the value is negative, the flow is in the opposite direction.

When more than one Flow is connected to a Stock, it is important to consider how they should interact with one another. NetLogo will not enforce that the Flows out of a stock occur in any particular order. Also, NetLogo will not ensure that the sum of Flows out of a Stock are less than or equal to the value of the Stock. These behaviors can be implemented explicitly when creating the Expression for a Flow.

For example, if the Flow is defined as a constant value, 10, you can ensure it never draws more than the value of the Stock by using the min primitive: min (list stock 10). If I want Flow A to deplete a Stock before Flow B is calculated, I can link Flow A to Flow B and modify Flow B to subtract Flow A's value from the stock: min (list (max (list 0 (stock - flow-a))) 10).

Link

To create a Link, click and hold on the starting point for the link -- a Variable, Stock or Flow -- and drag the mouse to the destination Variable or Flow.

Working with Diagram Elements

When you create a Stock, Variable, or Flow, you see a red question-mark on the element. The question-mark indicates that the element doesn't have a name yet. The red color indicates that the Stock is incomplete: it's missing one or more values required to generate a System Dynamics model. When a diagram element is complete, the name turns black.

Selecting: To select a diagram element, click on it. To select multiple elements, hold the shift key. You can also select one or more elements by dragging a selection box.

Editing: To edit a diagram element, select the element and press the "Edit" button on the toolbar. Or just double-click the element. (You can edit Stocks, Flows and Variables, but you can't edit Links).

Moving: To move a diagram element, select it and drag the mouse to a new location.

Editing dt

screen shot

On the right side of the toolbar is the default dt, the interval used to approximate the results of your System Dynamics model. To change the value of the default dt for your aggregate model, press the Edit button next to the dt display and enter a new value.

Errors

When you click the "check" button or when you edit a stock, flow, or variable the modeler will automatically generate the NetLogo code the corresponds to your diagram and try to compile that code. If there is an error the Code tab will turn red and a message will appear, and the portion of the generated code that is causing the trouble will be highlighted.

screen shot

This should give you a better idea which element in the diagram is causing the problem.

screen shot

Code Tab

The System Dynamics Modeler generates NetLogo variables and procedures based on the contents of your diagram. These procedures are what make the diagram actually perform calculations. The Code tab in the System Dynamics Modeler window displays the NetLogo procedures generated from your diagram.

You can't edit the contents of the Code tab. To modify your System Dynamics mode, edit the diagram.

Let's take a closer look at how the generated code relates to the diagram.:

The variables and procedures defined in this tab are accessible in the main NetLogo window, just like the variables and procedures you define yourself in the main NetLogo Code tab. You can call the procedures from the main Code tab, from the Command Center, or from buttons in the Interface tab. You can refer to the global variables anywhere, including in the main Code tab and in monitors.

There are three important procedures to notice: system-dynamics-setup, system-dynamics-go, and system-dynamics-do-plot.

system-dynamics-setup initializes the aggregate model. It sets the value of dt, calls reset-ticks, and initializes your stocks and your converters. Converters with a constant value are initialized first, followed by the stocks with constant values. The remaining stocks are initialized in alphabetical order.

system-dynamics-go runs the aggregate model for dt time units. It computes the values of Flows and Variables and updates the value of Stocks. It also calls tick-advance with the value of dt. Converters and Flows with non-constant Expressions will be calculated only once when this procedure is called, however, their order of evaluation is undefined

system-dynamics-do-plot plots the values of Stocks in the aggregate model. To use this, first create a plot in the main NetLogo window. You then need to define a plot pen for each Stock you want to be plotted. This procedure will use the current plot, which you can change using the set-current-plot command.

The System Dynamics Modeler and NetLogo

The diagram you create with the System Dynamics Modeler, and the procedures generated from your diagram, are part of your NetLogo model. When you a save the NetLogo model, your diagram is saved with it, in the same file.

Tutorial: Wolf-Sheep Predation

Let's create a model of Wolf-Sheep Predation with the System Dynamics Modeler.

Step 1: Sheep Reproduction

Our model will have a population of wolves and a population of sheep. Let's start with the sheep. First, create a Stock that holds a population of Sheep.

You see a Stock with a red question-mark in the middle.

screen shot

Our sheep population can increase if new sheep are born. To add this to our diagram, we create a Flow into the stock of sheep.

The number of sheep born during a period of time depends on the number of sheep that are alive: more sheep means more reproduction.

The rate of sheep births also depends on some constant factors that are beyond the scope of this model: the rate of reproduction, etc.

Your diagram should look something like this:

screen shot

The sheep-births Flow has a red label because we haven't given it an expression. Red indicates that there's something missing from that part of the diagram.

The amount of sheep flowing into our stock will depend positively with the number of sheep and the sheep birth rate.

We now have a complete diagram. To see the NetLogo code generated by our diagram, you can click on the Code tab of the System Dynamics Modeler window. It looks like this:

screen shot

Step 2: NetLogo Integration

Once you create an aggregate model with the System Dynamics Modeler, you can interact with the model through the main NetLogo interface window. Let's build our NetLogo model to run the code generated by our diagram. We'll need a setup and go buttons which call the system-dynamics-setup and system-dynamics-go procedures created by the System Dynamics Modeler. And we'll want a monitor and a plot to watch the changes in sheep population.

Now we're ready to run our model.

Notice what happens. The sheep population increases exponentially. After four or five iterations, we have an enormous number of sheep. That's because we have sheep reproduction, but our sheep never die.

To fix that, let's finish our diagram by introducing a population of wolves which eat sheep.

Step 3: Wolf Predation

Now we're really done.

You see a plot of the populations that looks like this:

screen shot