# Mathematica Link

NetLogo 5.0.3 User Manual

## What is it?

The NetLogo-Mathematica link provides modelers with an easy to use, real-time link between NetLogo and Mathematica. Together, these tools can provide users with a highly interactive, self-documenting work flow that neither can provide alone.

Mathematica includes many of the tools that agent-based modelers rely on throughout the research process: advanced import capabilities, statistical functions, data visualization, and document creation. With the NetLogo-Mathematica link, you can run all of these tools side-by-side with NetLogo.

Because all Mathematica documents, or notebooks, contain comments, code, images, annotations, and interactive objects, the integration of NetLogo and Mathematica provides a more complete solution for complex model exploration for students and researchers alike.

The basic functionality of the link is much like the NetLogo Controlling API: you can load models, execute commands, and report back data from NetLogo. Unlike the Controlling API, which is based on Java, all interactions with the link are interpreted, making it ideal not only for rapidly designing custom BehaviorSpace-like experiments, but also as a companion to NetLogo in debugging your model.

For more information about Mathematica, please visit the Wolfram Research web site.

## What can I do with it?

Here are a few examples of what you can do with the Mathematica-NetLogo link.

- Analyze your model in real-time with seamless two-way data conversion
- Develop high quality, custom visualizations of model data
- Collect detailed simulation data across large multi-dimensional parameter spaces
- Rapidly develop interactive interfaces for exploring model behavior
- Have direct access to patches and network data with built-in functions

## Installation

The NetLogo-Mathematica link requires Mathematica 6 or greater. (Mathematica 7 works.) To install the NetLogo-Mathematica link:

- Go to the menu bar in Mathematica
- Click on File and select Install...
- In the Install Mathematica Item dialog
- Select Package for Type of item to install
- Click Source, and select From file...
- In the file browser, go to the location of your NetLogo installation,
- click on the Mathematica Link subfolder, and select NetLogo.m.
- For Install Name, enter NetLogo.

You can either install the NetLogo link in your user base directory or in the system-wide directory. If the NetLogo link is installed in the user base directory, other users on the system must also go through the NetLogo-Mathematica link installation process to use it. This option might be preferable if you do not have permission to modify files outside of your home directory. Otherwise, you can install NetLogo-Mathematica link in the system-wide Mathematica base directory.

## Usage

This section will very briefly introduce how to use the NetLogo-Mathematica Link. It will show you how to load the NetLogo-Mathematica link package, start NetLogo, execute commands, and retrieve data from NetLogo.

Loading the package: Once the NetLogo-Mathematica link is installed, you can load the package by entering the following into your Mathematica notebook:

> `<<NetLogo``

Launching NetLogo from Mathematica: To begin your NetLogo session in Mathematica, type the following into your notebook:

> `NLStart["your netlogo path"];`

where "your netlogo path" is the directory that netlogo is located in. Typically on a Mac this will be "/Applications/NetLogo 5.0/"

Loading a model: To load a model, you must specify the full path of the model. In this example we will load the Forest Fire model, and the path will be given using the typical Mac install location.

> `NLLoadModel["/Applications/NetLogo 5.0/models/Sample Models/Earth Science/Fire.nlogo"];`

Executing a NetLogo command: Commands can be executed by passing a string of commands to `NLCommand[]`. The `NLCommand[]` function automatically splices common Mathematica data types into strings suitable for NetLogo. The following commands set the density using a single string, or set the density using a Mathematica defined variable, `myDensity`.

> `NLCommand["set density 50"];
> myDensity = 60;
> NLCommand["set density", myDensity];`

Reporting information from NetLogo: NetLogo data can be reported back to Mathematica using `NLReport[]`. This includes numbers, strings, boolean values, and lists.

> `NLReport["count turtles"];
> NLReport["[(list pxcor pycor)] of n-of 10 patches"]`

For more information, see the NetLogo-Mathematica Tutorial notebook included with NetLogo. The notebook walks you through the process of using the link, with many examples along the way. If you do not have Mathematica, but are considering using the link, you can download a PDF of the evaluated tutorial.

## Known Issues

- A NetLogo session cannot be quit without exiting J/Link (the Java-Mathematica link) entirely. This may disrupt other packages that make use of J/Link.
- If a model loaded with the NetLogo-Mathematica link uses a NetLogo extension, the extension must be located in the same directory as the model itself. If the extension is located in NetLogo's application-wide extensions directory, it will not be found.
- Calls to NetLogo, such as `NLCommand[]` and `NLReport[]`, cannot be aborted.

## Source code

The source code for the NetLogo-Mathematica link is in the public domain. It is hosted on line at https://github.com/NetLogo/Mathematica-Link.

## Credits

The primary developer of the NetLogo-Mathematica link was Eytan Bakshy.

To refer to this package in academic publications, please use: Bakshy, E., Wilensky, U. (2007). NetLogo-Mathematica Link. http://ccl.northwestern.edu/netlogo/mathematica.html. Center for Connected Learning and Computer-Based Modeling, Northwestern University, Evanston, IL.