Unofficial features

These features are not officially supported. They are (mostly) not in the User Manual and they may not continue to exist or work in future versions of NetLogo. If any of these are important to your work, stay in touch with the devel team about their status.

Primitives

• You can quickly open any model in the Models Library by typing a name, or a part of its name, into the Command Center, preceded by three underscores. For example, to open Flocking, you might type ___flock
• __reload will reload the current model from disk
• __pwd will print the working directory
• __check-syntax <string> reports a string result indicating whether was successfully parsed as a NetLogo statement. Either the result is the empty string "", indicating that string will not result in a compiler error if immediately passed to run, or it is an error message indicating the compile error that occurred.
• __set-line-thickness sets the thickness of lines in the shape ( if any are contained in the turtles current shape). it takes a double measured in patches. So 1.0 means one patch wide, zero will always be 1 pixel wide regardless of patch size. (This one is actually in the User Manual.)
• __change-topology sets the wrapping in x and y directions
• __export-drawing exports only the drawing layer to an image file

Narrowcast plotting

HubNet can control plots specific to each client:

• __hubnet-make-plot-narrowcast <plotname> designates a plot as narrowcast.

Both the model and the client should have a plot named plotname. The plot can then be controlled with the following narrowcast plotting primitives.

• __hubnet-clear-plot <client-id>
• __hubnet-plot <client-id> <number>
• __hubnet-plot-pen-down <client-id>
• __hubnet-plot-pen-up <client-id>
• __hubnet-plot-point <client-id> <number> <number>
• __hubnet-plotxy <client-id> <number> <number>
• __hubnet-ppd <client-id>
• __hubnet-ppu <client-id>
• __hubnet-set-histogram-num-bars <client-id> <number>
• __hubnet-set-plot-pen-interval <client-id> <number>
• __hubnet-set-plot-pen-mode <client-id> <number>

Preview images

Every model in the models library needs a PNG preview image. This image is used in the Models Library window. The preview image should have the same name, and live in the same directory, as the model, but extension .png instead of .nlogo.

NetLogo can automatically generate preview images for models. From the command line, ./sbt all-previews redoes the whole models library and ./sbt preview can be used to remake a single preview.

By default, NetLogo generates a preview image by executing random-seed 0 setup repeat 75 [ go ], and then exporting the contents of the 2D view. You can specify custom preview commands for a particular model by hand-editing the model file and putting your custom preview commands in the section near the end right after the NetLogo version, or by using the Preview Commands Editor (accessible from the Tools menu). (Even if you specify custom commands, NetLogo still does random-seed 0 before running them, so you don't need to set the random seed yourself unless you don't like 0.)

For example, you'll notice the custom preview commands in the Wolf Sheep Predation model:

...
false
0
Polygon -7500403 true true 270 75 225 30 30 225 75 270
Polygon -7500403 true true 30 75 75 30 270 225 225 270

@#$#@#$#@
NetLogo 3.0beta2
@#$#@#$#@
set grass? true
setup
repeat 75 [ go ]
@#$#@#$#@
@#$#@#$#@
@#$#@#$#@

If a model needs a hand-generated preview (for example, a model that requires user interaction), set the custom preview commands to a single pseudo-command, need-to-manually-make-preview-for-this-model. Then NetLogo will ignore that model when generating previews.

Note that custom preview commands are also used to generate model checksums, for use in regression testing the compiler and engine.

Applets

• Right-clicking the white background of saved applet will tell you what version of NetLogo the applet was created in, what OS and VM you're running under, etc

Devel-only

The features that follow are probably only of interest to Scala/Java developers.

Applets/embedding

You can test org.nlogo.lite.AppletPanel (used in applets and embedding) by double clicking NetLogoLite.jar or running sbt run-main org.nlogo.lite.AppletPanel; you'll get a file chooser dialog to pick a model; of course this doesn't catch all bugs that might occur when actually embedded in an applet or application, but it's helpful for some kinds of testing.

If you pass a model path (relative or absolute) on the command line, that model will be opened.

Primitives

• You can quickly convert a Models Library model into a "normal" model (allowing you to save over it) by using the __edit command. This is a bit dangerous, but it's very nice since it allows you to load a model using triple-underscore and then quickly save it. Note that the title bar does not reflect the change until you save the model. Note that the command will complain if it doesn't find a .git directory under models, since if you're not doing this from a Git repo, you're probably making a mistake.
• __git lets you commit a model to Git or run another Git command on the currently open model. Note it does not save the model for you; normally, you'll need to use __edit first, then File->Save, then __git "commit".
• __stdout and __stderr let you send output to the standard output or standard error streams.
• __dump reports a string representation of the compiled form of your program; this is helpful for debugging the compiler.
• __dump1 reports a string representation of the current procedure only, so you can get a dump of stuff other than the procedures tab
• __done kills the current context; this is used internally in a few places, but might be useful during debugging as well
• __boom is a reporter that does "throw new EngineException", which can be useful during testing and debugging
• __ignore is a command that takes a single input and does nothing with it. May be useful when writing tests
• __frames is a reporter that tells you how many times the graphics window is been painted since startup or the last time you called reset-timer -- handy for measuring graphics performance
• __dump-extensions prints information about loaded extensions; __dump-extension-prims prints information about loaded extension primitives
• __reload-extensions forces NetLogo to reload all extensions the next time you compile your model.
• __random-state reports a very long string encapsulating the state of the random number generator. it's the same string that export-world writes at the top of export files.

Command line flags

You can pass these to NetLogo in any of the following ways:

make go ARGS="arg1 arg2 ..."
java -jar NetLogo.jar arg1 arg2 ...

or by editing dist/NetLogo.install4j (Windows) or dist/NetLogo.app/Contents/Info.plist (Mac OS X) or netlogo.sh (Linux/other)

• --events turns on event tracing, so you can see what components raise events and what components handle them; note that some very commmon events, e.g. PeriodicUpdateEvent, are omitted from the trace
• --open MODELNAME opens the given model in "library" mode which forces Save-As if you try to save (you may use an absolute or relative path)
• --launch MODELNAME opens the given model in normal mode so you can save your changes in place (you may use an absolute or relative path)
• --magic MODELSTRING opens a model matching the given string (just like triple underscore)
• --version prints the NetLogo version number and exits; this is used during the installer-building process
• --shortversion prints the NetLogo version number, not including the revision (e.g. "Rev B"), and exits; this is used during the installer-building process

Model checksums

Model checksums make sure that when we change NetLogo, we don't inadvertently change the results of model runs.

• The file test/checksums.txt has a list of models and checksums. The first column is the model name; the second column is the checksum of the world after running the model's preview commands, and the third column is the checksum of the contents of the 2D view after running the model's preview commands. There is also a file for 3D, test/checksums3d.txt and the headless project test/checksums-headless.txt.

• Variants for a model can be defined in the test/checksum-variants.txt file. Each model is defined on a line starting with * and then the relative model path. The variants go the lines after, and are the raw NetLogo commands to setup the variant to checksum. One variant is defined per line.

• ./sbt netlogo/checksum adds an entry for a new model, or updates the entry of a model in checksums.txt. It runs the preview commands for the model and calculates both a checksum of the world and of the contents of the view. Type, for example, in sbt, checksum "models/Sample Models/Biology/Wolf Sheep Predation.nlogo"

• To generate new checksums for the entire library, type ./sbt netlogo/allChecksums. For the headless engine ./sbt headless/allChecksums and 3D would be ./sbt threed netlogo/allChecksums.

• To check current checksums against the values saved in checksums.txt, type ./sbt netlogo/testOnly *TestChecksums, or ./sbt headless/testOnly *TestChecksums for checksums-headless.txt or ./sbt threed netlogo/testOnly *TestChecksums for checksums3d.txt. This is mostly useful for the CI/build environment to catch unintended changes. If you suspect there are changes or differences in the checksums, you're better off re-generating the checksums from scratch using allChecksums (see above), comparing the changes using git diff, and making sure the changes are expected and merging if so or reverting if not. Running the TestChecksums will tell you that the checksums have changed, but won't update the files to commit the changes if the differences are intentional.

HubNet stuff

• The reporters __hubnet-in-q-size and __hubnet-out-q-size will tell you if HubNet's internal queues are getting backed up

• A "robo-client" is available for testing HubNet models: it simulates a human participant by randomly generating button clicks, slider moves, etc. in the client interface; open a robo-client with __hubnet-robo-client num; where num is the number of milliseconds between client sends; contact the HubNet team for details

You can pass these command line arguments to HubNet:

• --robo num opens a robo client that sends a widget change every num milliseconds. if num is not specified, 500 is used.

• --ip hostname or ip use a specified server as the host of a simulation

• --id user-id enters user-id into the user name field

If both --ip hostname or ip and --id user-id are present, the client connects automatically using these parameters. You don't have to press the enter in the client. This is useful for automating runs.

• __hubnet-broadcast-user-message and __hubnet-send-user-message are analogous to user-message to all clients and one client respectively
• __hubnet-create-client creates a local client. this is the same as pressing the Local button in the HubNet Control center. an 'invisible' client is created in headless.
• __hubnet-send-from-local-client client-name tag value (Headless only) - send a message from a local client to the server
• __hubnet-set-view-mirroring on-or-off (only tested in Headless) - takes a boolean argument and turns view mirroring on or off.
• __hubnet-wait-for-clients nr-clients-to-wait-for timeout - waits up to timeout ms for the specified number of clients to connect. throws an exception if that number of clients didn't connect before the timeout.
• __hubnet-wait-for-messages nr-messages-to-wait-for timeout - waits up to timeout ms for the specified number of messages to arrive. throws an exception if that number of messages didn't arrive before the timeout.