NetLogo

From SESLINK Wiki
Revision as of 13:56, 29 March 2017 by Henrik (talk | contribs) (Reverted edits by Henrik (talk) to last revision by Romina)
Jump to navigation Jump to search

NetLogo is the main modeling software used by the SESLINK group. It is available from the NetLogo webpage. This page outlines a few tips and tricks for using NetLogo more effectively.

Running NetLogo headless

NetLogo can be run in what is called "headless mode", which means that it runs simulations without showing a graphical user interface (GUI). This speeds up computation quite a bit, but has the drawback that there is no user feedback during the simulation run.

To run NetLogo headless, one needs to invoke it from the command line. The commands for this are explained in the NetLogo documentation.

In order to make this process a little bit easier, the SESLINK group has a ready-made package for running NetLogo headless. It's designed for UNIX systems (Linux and MacOS X) and runs in the command line. Please note that running NetLogo headless requires that the Java Runtime Environment (JRE) is installed on the machine. This is already in place on machines provided by the project, but your local machine may need to be updated.

Step-by-step guide:

  • Unless you have very specific reasons for not doing this, please make sure that you model is updated to run on NetLogo 6.0.0. This is done by loading and saving the model in NetLogo 6 on your own machine.
  • Update your Java version. NetLogo 6 requires Java 1.8.
  • Download a NetLogo package from one of these links:
    • NetLogo 6.0.0 (this is the preferred version)
    • NetLogo 5.3.1 (legacy version, do not use unless you absolutely have to)
    • Note that the NetLogo 6.0.0 package is the default and has been shown to work with more models. The NetLogo 5.3.1 package may cause problems with some models, and should only be used if the model cannot be upgraded to NetLogo 6.0.0 for some reason.
  • Put it in the desired location on the machine that will be running the simulation (for example on an AWS machine)
  • Unzip it using the unzip command: unzip netlogo-headless.zip
  • Put your .nlogo file and any accompanying files in the same directory
  • Invoke the run shell script using ./run for Linux/MacOS or run for Windows.
    • The script should now provide usage instructions. If you get an error, please consult a senior modeler in the group.
    • The syntax for running an experiment is: ./run MODEL EXPERIMENT for Linux/MacOS and run MODEL EXPERIMENT for Windows. If we want to run the Exp1 experiment for the MyModel model on a Linux or MacOS machine, the command is: ./run MyModel.nlogo Exp1
  • The results will be saved in the NetLogo table format to a file named MODEL_EXPERIMENT_output.csv. As per the example above, the output file becomes MyModel_Exp1_output.csv

The triple quotes problem

One common problem with putting NetLogo runs into R is that the output from NetLogo encapsulates string (text) values in triple quotes ("""text"""). This confuses R, and makes importing the data somewhat difficult. To solve this we have written a small script that fixes the problem. It requires Python to be installed on your machine. This is already in place on machines provided by the project, but your local machine may need to be updated.

Step-by-step guide:

  • Download the file from here
  • Put the script in the same folder as the data file you want to process
  • Invoke the script using: python stripquotes.py FILENAME where filename is the name of your data file.
    • For example, if you want to process the data file MyModel_Exp1_output.csv you issue the command python stripquotes.py MyModel_Exp1_output.csv
  • The end result will be written to the file fixed_FILENAME. Using the previous example, the file will be called fixed_MyModel_Exp1_output.csv

Please note that running this script on a data file will double the amount of storage space used for data. If you have large data files this may create significant storage requirements.

NetLogo model documentation

Henrik has written a small utility to generate documentation of NetLogo code, called NetLogoDoc. It's inspired by the PyDoc and JavaDoc documentation generators. As of January 2017 it's still very primitive, but can be helpful if one is trying to collaborate with other researchers. It requires Python to be installed on your machine. This is already in place on machines provided by the project, but your local machine may need to be updated.

It can be found in the NetLogoDoc section of Henrik's private github account. This page also contains usage instructions.

As with any software, NetLogo has its fair share of bugs. Fortunately, the developers are very responsive and keep track of the issue tracker on the NetLogo github page.

If you think you found a bug in NetLogo, try to replicate it and make sure that it is in fact a real bug and not just a bug in your code. If it turns out that you found an actual bug, please report it along with all the details needed for the developers to try to replicate it and understand why it happens. Here's an example of a bug we previously reported with the NetLogo 5->6 automatic converter: NetLogo issue #1283.

Conflicts through git and how to fix it

This section is covering problems that originate from .nlogo file conflicts beyond the code section.

  • Changes in the user interface
  • Changes in experiments, stored in xml - be careful when the type or number of variables changed, because the git auto-merge function is destroying the logic behind
Retrieved from "https://seslink.org/wiki/index.php?title=NetLogo&oldid=446"