Experimental: Extensions

Extensions provide a way for NetLogo code to use functionality not provided by the core NetLogo primitives. Very often this involves interacting with external software and services, or performing specialized calculations that are difficult or tedious to implement in NetLogo. More information can be found in the NetLogo desktop documentation for extensions and the list of extensions for desktop. Very few extensions are supported in NetLogo Web at this time.

In NetLogo Web the target for an extension must be Javascript, and at the moment the only way to include an extension is by bundling it with the NetLogo Web code itself. This is all experimental, and we may change the definition file format or the way extensions are loaded as needed for future work. Longer-term the NetLogo team has plans to provide a mechanism to allow inclusion of third party extensions that are external to the NetLogo Web site, but that work is not yet complete.

Creating an extension requires providing at least two items to the Tortoise compiler and engine. First is a definition file that explains the syntax of the commands the extension provides. This must be read at NetLogo code compile time, since extensions involve statements in NetLogo code that will need to be parsed by the compiler. Second is the Javascript code that will actually run the commands during execution by the engine. See the definition and the code for the logging extension as examples.

Format for Defining Extensions

The following describes the grammar for defining an extension's .json defs file.

type ArgType = "unit" ('void' type; only appears in return type; indicates that this is a command, not a reporter) | "agentset" | "agent" | "booleanblock" | "boolean" | "bracketed" | "codeblock" | "commandblock" | "command" | "linkset" | "link" | "list" | "nobody" | "numberblock" | "number" | "optional" | "otherblock" | "patchset" | "patch" | "readable" | "reference" | "reporterblock" | "reporter" | "string" | "symbol" | "turtleset" | "turtle" | "wildcard"

type PrimDef =
  {
    name: string (name in NetLogo, used to access the Javascript implementation as a field of the `prims` object given by the extension)
  , argTypes: array[ArgType | { type: ArgType, isRepeatable: boolean (default: false) }] (default: [])
  , returnType: ArgType (default: "unit")
  , isInfix: boolean (default: false)
  , precedenceOffset: number (default: 0)
  , defaultArgCount: number (default: 0)
  , minimumArgCount: number (default: 0)
  , agentClassString: AgentClassString (string like "OTPL", "O---", "-TP-", and so on, default "OTPL")
  , blockAgentClassString: Optional[AgentClassString]
  }

type ExtDef =
  {
    name: string
  , prims: array[PrimDef]
  }

Building, Testing, and Packaging

Firstly, note that there is a Scala macro for the extension definition reader in the macros project. We have added an sbt task that should handle automatically re-compiling these macros each time there is a change in an extension's JSON file. This means when you run compilerJVM/compile the extensions macros will be recompiled automatically only if there is a change. This does not affect how the engine is compiled when you change the extension's code, only the JSON definitions that are provided to the compiler.

If for some reason you need to re-run the macros compilation (perhaps you believe it's not regenerating the extensions list for the compiler correctly), in an sbt console you can do this with the clean command for the JS and JVM versions of the project:

; macrosJS/clean ; macrosJVM/clean

You can test your extension with NetLogo language tests. It's often faster to develop your extension using language tests (if possible), then complete interactive tests after. Just add a text file with the tests in resources/main/test/commands then you can run in an sbt console (where Extension would match the name of the text file):

netLogoWeb/testOnly *TestCommands -- -z Extension

Once you're ready to publish your changes to test them out in a real environment, like Galapagos or your own project, you can locally publish the NetLogo JVM compiler (publishLocalVersioned compilerJVM) or the Javascript compiler and engine (publishLocalVersioned netLogoWeb) for use. More info on that in the Galapagos wiki.

Bundled Extensions

Some extensions are already bundled with NetLogo Web. These extensions are all experiemental and subject to change:

• HTTP Req Extension - for sending HTTP requests.
• CODAP Extension - for interacting with the CODAP service.
• NLMAP Extension - a basic map or dictionary data type.
• Experimental: Logging Extension - for logging model data to strings.
• Experimental: CSV Extension* - for creating or splitting CSV strings.
• Array* - A simple array data structure for models
• Fetch* - for getting data into NetLogo Web from external sources, like files and URLs.
• Dialog* - various dialogs to interact with the user of a model.
• ExportThe* - for converting NetLogo data into strings.
• ImportA* - for reading imported data back into NetLogo.
• Matrix* - matrix data type and related mathematical operations - note some primitives are still unimplemented around Eigen values and vectors.
• SendTo* - for sending data from NetLogo Web to a local file of the user's choosing.
• Store* - for a persistent data store between model loads.
• Table* - a key/value data structure for models

Info and links to docs for many of these extensions is in the NetLogo Web release notes.

A * indicates the extension has a compatible NetLogo desktop version.

Unimplemented Extensions

The following extensions come bundled with NetLogo desktop, but are not yet supported by NetLogo Web.

• Arduino
• Bitmap
• GIS
• Gogo
• LevelSpace
• Network
• Palette
• Profiler
• Python
• R
• Rnd
• Sound
• Time
• Vid
• View2.5D