Displaying Output (Logging) in NetLogo

nimeshneema · October 11, 2024, 9:18am

Displaying Output (Logging) in NetLogo

Displaying output (also known as logging) refers to showing specific information in a designated area. Such an area is commonly called the Console in most programming environments. While the appearance, capabilities and terminologies may differ slightly across programming environments, the purpose remains the same, i.e. to have an area where auxiliary information about the program’s execution can be displayed. Almost all programming environments offer a logging facility.

Now logging is a vital part of program development, testing and deployment. Logging helps in visually verifying the correctness of variables and expressions at certain points in the program’s execution. During development, while the program source code is continuously being tested and updated, logging helps as a debugging aid, to check whether values of certain variables and expressions are as expected. The testing phase uses logging to verify the correctness of data at various stages of program execution, spot any discrepancies and make necessary fixes in the code. But the story does not just end here. Logging is also useful for displaying important output to end-users or as a method for auditing and record-keeping.

Similar to other programming environments, NetLogo provides several methods to display log output. In NetLogo, log output appears in the Command Center at the bottom of the Interface tab. The Command Center consists of two parts, with the larger portion displaying output. For our discussion, we will refer to this part as the console.

Commands can be typed into the command input box at the bottom of the Command Center, and the relevant output or error message will be displayed in the console. However, NetLogo also provides primitives (built-in commands) for displaying output programmatically.

NetLogo provides four primitive (built-in commands) that can be used to send output to the console:

print
show
type
write

All four of the above commands have a similar usage. Each command is followed by a value, which can be a constant, a variable name or an expression. The value is evaluated at the time of invocation of the command and the result is displayed in the Console.

Why four different commands you may ask? Well, the designers of NetLogo may have thought of providing four different commands to serve slightly different use cases. Our aim here is to establish a solid understanding of and differences between these four commands and clear any confusion between them.

The commands differ in what kind of values they can handle, how they handle it and how they render the output. Let’s dissect them, starting with an informal summary of each one of them:

print: Displays the value and ends the line, so that any subsequent output will get displayed on a separate (new) line.
show: In addition to what print does, this command prepends the output with the agent type that invoked the command. Any textual data (string) is quoted inside double quotes.
type: The line is not ended (terminated) after displaying the output. This causes any subsequent output to get appended to the current output without a change of line (newline). This is useful when output from multiple concurrent invocations of this command needs to be displayed on a single line.
write: This command is similar to the type command, but in addition, strings are quoted inside double quotes. Also, write cannot be used to display agentset.

Now let’s take a look at what are the various types of values available in NetLogo. A constant or a variable in NetLogo can be a boolean (true or false value), number (integer or with decimal point), textual (string), list (sequential collection of items), or an agentset (a set of agents).

If we look at the official documentation in NetLogo Dictionary, the syntax for all four primitives is similar, command followed by value parameter.

print value
show value
type value
write value

An easy-to-remember way regarding the working of each command is as follows:

print is useful for simple printing. The objecting is to print, hence the name. Each invocation of the print command is intended to print a line of output and move on.
show is useful when we want to “peek” into the value of some variable or expression, most likely for debugging purposes, i.e. to verify that values are correct at certain stages of program execution. This could explain why the output is prepended with the agent type that is “showing” the output. Strings are also quoted in double quotes to help with easy identification.
type can be thought of as analogous to a typewriter. When typing, we do not tend to automatically move to the next (new) line.
write can be thought of as a human being writing. Now unlike a typewriter, humans tend to quote strings. This is exactly what write does. Also, a set is not a “natural” data type when humans communicate, hence write cannot work with agentsets.

So as we can see, show makes more sense while debugging code. It is more useful for the developers/implementors of a model.

print makes sense when we wish to display some meaningful information to the users of the model.

Along similar lines, type is useful for debugging but when we wish to show single-line output and write is useful for consumers/users of the model.

To summarise:

print and show add a new line after displaying their output, while type and write do not.
show and write quotes strings in double quotes, while print and type do not.
show prepends the agent that is showing the output, print, type and write do not.

I hope the explanation above both clears any confusion between the available output primitives as well as helps users remember the capabilities of each one of them.

Here’s a sample code snippet that can be used to see the primitives in action:

to setup
  clear-all

  create-turtles 5 [
    setxy random-xcor random-ycor
    set size 2
  ]

  reset-ticks
end

to go
  go-print
  go-show
  go-type
  go-write
  tick
end

to go-print
  print true
  print 1
  print 3.14
  print "NetLogo"
  print [1 2 3 4]
  print turtles
  print turtle 0
  print patch 0 0
end

to go-show
  show true
  show 1
  show 3.14
  show "NetLogo"
  show [1 2 3 4]
  show turtles
  show turtle 0
  show patch 0 0
end

to go-type
  type true
  type 1
  type 3.14
  type "NetLogo"
  type [1 2 3 4]
  type turtles
  type turtle 0
  type patch 0 0
end

to go-write
  write true
  write 1
  write 3.14
  write "NetLogo"
  write [1 2 3 4]
  write turtle 0
  write patch 0 0
end

jzkelter · October 14, 2024, 12:57am

Very thorough explanation of these four primitives! I’m wondering if you are assuming readers will have some NetLogo background already. Like are you assuming they have already done the three official tutorials? Who are your intended audience?

nimeshneema · October 15, 2024, 8:19am

Thank you for the kind feedback! The intended audience is primarily those who are new to NetLogo and may have little to no prior programming experience. They may or may not have completed the official tutorials.

While the official documentation, programming guide, and the dictionary are excellent resources, I believe they serve more as references or explainers for users with some programming background. My goal is to compile more approachable and beginner-friendly introduction to NetLogo’s concepts, with a focus on explanation and gradual learning over demonstration.

jzkelter · October 15, 2024, 10:25pm

That sounds great! In case you aren’t aware of them, I just made this post about the Official NetLogo Tutorials. You might want to look at those to avoid duplicating anything (so far, you haven’t at all). You also might consider suggesting people go through those before your tutorials so you can assume they already have some basic familiarity with what is covered there.