Getting started with NetLogo

Quickstart Tutorial

Step 1: Configure Library Properties

1. Open the SyncroSim GUI and select File I New.
2. Select the netlogo base package and the NetLogo Example template; specify a file name and folder location for your netlogo SyncroSim library and click OK.
3. The SyncroSim library explorer should now display your new netlogo library.
4. Highlight your netlogo library in the library explorer and select File I Library Properties.
5. On the Options I NetLogo of the Library Properties specify the NetLogo executable filename where the NetLogo.exe file is located. For the x64 version of NetLogo This is typically “C:\Program Files\NetLogo 6.X.X”.
6. In the Library Properties for NetLogo you can also select to Run in window which show the NetLogo GUI at runtime. This is useful for initially debugging your model, but can be cumbersome if you are running many model realizations and scenarios.

Step 2: View Definitions

1. In the SyncroSim library explorer right click on Definitions and select the Symbols tab. The netlogo template library has been preloaded with a very simple example agent-based model of biocontrol agents, or Bugs, looking for and eating an invasive plant on the landscape. The model is written in a .nlogo code file that ships with the template library. In this file, certain variables defined in the code can be set in the SyncroSim user interface by using Symbols. A Symbol is simply a collection of characters that denotes where a specific value should be inserted into the nlogo code file at runtime. Symbols can be used to set state variables. Symbols can also be used to set input files that need to be loaded by NetLogo at runtime, such as a raster specifying the starting landscape conditions. Details on how Symbols are used in the NetLogo code files will be explained in the documentation section on NetLogo Code.
2. The last tab in the Definitions for the netlogo package is for Output Variables. The example library contains four output variables: Closed, Open, and Invaded are used to denote the amount of area in these three possible discrete vegetation states. The output variable landCover is used to represent a map of the landscape state. Like Symbols, Output Variables are used in the NetLogo code; their purpose is to allow SyncroSim to load NetLogo output into the model database and to display that output in the user interface. Further explanation on Output Variables is given in the section below on NetLogo Code.

Step 3: View Scenario Properties

1. In the SyncroSim library explorer right click on the scenario called 5 Bugs and select Open. This is a scenario used to represent 5 biocontrol agents, or Bugs, moving across the landscape and eating Invaded patches.
2. The Run Control property for this scenario is set to run 10 timesteps and 7 iterations. The timesteps will be used to define how many NetLogo ticks to run each iteration for. The NetLogo model will be run once per iteration.
3. The Script property points to the netLogoExample.nlogo code file that comes with the template library. The Script property also denotes the NetLogo Experiment name which is “experiment” by default in NetLogo. For more details on NetLogo experiments see the NetLogo Documentation on Behaviour Space.
4. On the Inputs property note that you can specify a starting number of Bugs for the simulation.
5. On the Input Files property you can specify the input ascii raster file that denotes the starting conditions for the landscape.

Step 4: Run the NetLogo Model

1. In the SyncroSim library explorer right-click on the scenario called 5 Bugs and select Run.
2. If you checked Run in window in the Options I NetLogo library property, you will see the NetLogo GUI open. Select setup then go followed by File I Quit. This will be repeated for every model realization.

Step 5: View Charts of Output

Once the simulation is complete, you can use the SyncroSim chart window to view NetLogo outputs. Note that you can disaggregate and include output for any of the variables defined in the project Definitions. You can also choose to use the rsyncrosim package to extract model output into R dataframes.

Step 6: View Maps of Output

The example library also contains a map that displays the Land Cover (Open, Closed or Invaded) for each cell at different realizations and time points. Mapping variables can be either discrete, such as in this example, or continuous. To view this map in the SyncroSim GUI you will need to use the SyncroSim map window.

Build Your Own Model

To learn how to build your own SyncroSim netlogo model, take a look at the example nlogo code file provided with the template library. Note that if you open this file as is with NetLogo you will receive several errors because it contains Symbols where SyncroSim will insert values at runtime.

NetLogo Code

Note that in the template library Definitions there are two symbols; INPUT_RASTER and NUM_BUGS. You can find these symbols in the example nlogo code file. For example, the number of Bugs at runtime will be set using the following code:

to setup-bugs
  create-bugs %NUM_BUGS% [
    set color black
    set shape "arrow"
    set size 2
  ask bugs [ setxy random-xcor random-ycor ]

  ]
end

and the initial landscape conditions raster will be loaded using this code:

 set patch-dataset gis:load-dataset %INPUT_RASTER%

At runtime, SyncroSim will replace the symbols with the values set by the user in the Scenario Properties. If you chose the SyncroSim Library Properties I Options I NetLogo I Run In Window option you will see that when NetLogo opens a copy of this file at runtime, and you can view the code where the symbols will be replaced by the values configured in the SyncroSim UI.

Note also that the Definitions contain a tab called Output Variables. These are used to load output into the SyncroSim library once the run is complete. Output variables can represent either state variables for charting or output raster files for mapping. In the template example there are three categorical variables used to represent the state of each cell on the landscape: Open, Closed, and Invaded. There is also a variable called landCover that is used for an output asc raster of the landscape state. You can see examples of how these variables are used in the example NetLogo code file. For example, in the following lines a csv file of the amount of area in each of the Output Variable land cover classes is written:

file-open %SSIM_VARIABLE_FILENAME%
  file-print csv:to-row (list %SSIM_ITERATION% ticks "Open" Open)
  file-print csv:to-row (list %SSIM_ITERATION% ticks "Closed" Closed)
  file-print csv:to-row (list %SSIM_ITERATION% ticks "Invaded" Invaded)
  file-flush ; Make sure that the output is saved to file
file-close

Each line being printed specifies the current iteration, timestep, output variable name and output variable value.

The following code writes a raster of the landCover output variable and prints a record to the csv catalog of output rasters to be loaded into the SyncroSim library.

gis:store-dataset patches_out (word %SSIM_NETLOGO_TEMP_FOLDER% "\\it" %SSIM_ITERATION% ".ts" ticks ".landCover.asc")

file-open %SSIM_VARIABLE_RASTER_FILENAME%
file-print csv:to-row (list %SSIM_ITERATION% ticks "Landscape Cover Map" (word %SSIM_NETLOGO_TEMP_FOLDER% "\\it" %SSIM_ITERATION% ".ts" ticks ".landCover.tif"))
file-close

The first part writes an ascii raster to the temporary runtime location. The second part creates a record of that raster in the csv catalog of output files that will be loaded into SyncroSim once the run is complete. The csv file contains a column for each iteration, timestep, output variable, and path to the output file.

You will have noticed that in the code examples shown above, there are other symbols bracketed by % characters. These are SyncroSim reserved symbols that are described in the next section.

Reserved Symbols for the SyncroSim netlogo Package

In addition to the symbols created by the user in the Definitions, there are a number of reserved symbols that you will find in the example nlogo file provided with the template library. These are values that are automatically set by SyncroSim at runtime and you can be used in your code when you create your own SyncroSim netlogo model. The symbols include the following:

  ;Current Iteration %SSIM_ITERATION%
  ;Number of Timesteps per Iteration %SSIM_TICKS%
  ;Output Variable Filename %SSIM_VARIABLE_FILENAME%
  ;Output Variable Raster Filename %SSIM_VARIABLE_RASTER_FILENAME%
  ;Temp Folder Path %SSIM_NETLOGO_TEMP_FOLDER%

Note that in this example, the number of timesteps to run is inserted by SyncroSim from the scenario Run Control property. Note also that the Output Variable File and the Output Variable Raster File are csv files with specified formats. See the code examples above, where these files are being written.

To use the number of timesteps set in Run Control, your code must include the following:

to setup
  __stdout (word "ssim-task-start=" %SSIM_TICKS%)
  ;_____________________________
  ;INCLUDE OTHER SETUP CODE HERE
  ;_____________________________
  reset-ticks
end

to go

  if (ticks = %SSIM_TICKS% + 1) [
    __stdout "ssim-task-end=True"
    file-close
    stop
  ]
  ;__________________________
  ;INCLUDE OTHER GO CODE HERE
  ;__________________________
  tick
  __stdout "ssim-task-step=1"
end

the calls to _stdout allow you to see the status of the NetLogo run progress on the SyncroSim GUI.