NetLogo

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, Gunvor has a ready-made package for running NetLogo headless. On Gunvor, NetLogo can be run using the netlogo-headless command. If we have a model named ModelA, and we want to run an associated experiment named ExperimentA (as defined in the BehaviorSpace window for the model), and capture the output as results.csv, we can invoke the following command:

 netlogo-headless ModelA ExperimentA results.csv

The command assumes that the path to the model file and the results file are both relative to where the command was invoked. Thus, it is not possible to invoke it with an absolute path for either model.

Note that the netlogo-headless command only works with models created for NetLogo 6.0 or newer. Models that were created using NetLogo 5 can most often be automatically updated to NetLogo 6 by simply opening them in NetLogo 6.x and saving the file.

You may also want to run the command wrapped in a screen session. This allows it to run on the server even if you get disconnected. Please see the screen manual for usage instructions.

Running netlogo experiments headless on Gunvor using tmux

1. copy netlogo file to gunvor (needs to be done before logging into gunvor)
   1. scp \path-to-modelfile\modelfile.netlogo gunvor:~/data/
2. log into gunvor
   1. ssh gunvor (if config file exists)
3. start tmux session
   1. tmux
4. start headless simulation
   1. netlogo-headless --model .Data/modelfile.netlogo --experiment "Name" --table output.csv
5. detach tmux session
   1. ctrl b d
6. check status of simulation
   1. htop -u maja
   2. q
7. access tmux session
   1. tmux attach
8. exit tmux session
   1. exit
9. pull data from gunvor to local directory
   1. scp gunvor:~/data/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.

Reporting bugs in NetLogo

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.

Error messages in NetLogo

These are sometimes not showing at all what is the problem. If you can't figure it out within a reasonable time, use the the Netlogo GitHib page to ask for help. They are usually fast in the experience of Nanda and Henrik. Emailing them turned out to be inefficient (no response - Nanda).

one known issue is that you cannot run behavior space if a plot is not compiled (red) sometimes. In the interface it cab work, but in behavior space it can cause trouble.

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

Henrik's tutorial from the 2016 retreat contains instructions on how to resolve various conflicts that may arise when working with NetLogo. Please see slide 30-34 in the presentation.