Controlling Guide

NetLogo User Manual

NetLogo can be invoked from another Java program and controlled by that program. For example, you might want to call NetLogo from a small program that does something simple like automate a series of model runs.

This section of the User Manual introduces this facility for Java programmers. We'll assume that you know the Java language and related tools and practices.

Note: The controlling facility is considered "experimental". It is likely to continue to change and grow. Code you write now that uses it may need changes in order to continue to work in future NetLogo versions.

Example (with GUI)
Example (headless)
Other Options
Conclusion

The NetLogo API Specification contains further details.

Example (with GUI)

Here is a small but complete program that starts the full NetLogo application, opens a model, moves a slider, sets the random seed, runs the model for 50 ticks, and then prints a result:

import org.nlogo.app.App;
import org.nlogo.compiler.CompilerException;
import java.awt.EventQueue;

public class Example1 {
    public static void main(String[] argv) {
        App.main(argv);
        try {
            EventQueue.invokeAndWait
                ( new Runnable()
                    { public void run() {
                        App.app.open
                            ("models/Sample Models/Earth Science/"
                             + "Fire.nlogo");
                    } } );
            App.app.command("set density 62");
            App.app.command("random-seed 0");
            App.app.command("setup");
            App.app.command("repeat 50 [ go ]");
            System.out.println
                (App.app.report("burned-trees"));
        }
        catch(Exception ex) {
            ex.printStackTrace();
        }
    }
}

In order to compile and run this, NetLogo.jar (from the NetLogo distribution) must be in the classpath.

Note the use of EventQueue.invokeAndWait to ensure that a method is called from the right thread. This is because most of the methods on the App class may only be called some certain threads. Most of the methods may only be called from the AWT event queue thread; but a few methods, such as commmand(), may only be called from threads other than the AWT event queue thread (such as, in this example, the main thread).

Rather than continuing to discuss this example in full detail, we refer you to the NetLogo API Specification, which documents all of the ins and outs of the classes and methods used above. Additional methods are available as well.

Example (headless)

The example code in this case is very similar to the previous example, but with methods on an instance of the HeadlessWorkspace class substituted for static methods on App.

import org.nlogo.workspace.HeadlessWorkspace;
import org.nlogo.compiler.CompilerException;

public class Example2 {
    public static void main(String[] argv) {
        HeadlessWorkspace workspace =
            new HeadlessWorkspace() ;
        try {
            workspace.open
                ("models/Sample Models/Earth Science/"
                 + "Fire.nlogo");
            workspace.command("set density 62");
            workspace.command("random-seed 0");
            workspace.command("setup");
            workspace.command("repeat 50 [ go ]") ;
            System.out.println
                (workspace.report("burned-trees"));
            workspace.dispose();
        }
        catch(Exception ex) {
            ex.printStackTrace();
        }
    }
}

In order to compile and run this, either NetLogo.jar or NetLogoLite.jar (from the NetLogo distribution) must be in your classpath. (The latter jar is smaller, but is only capable of headless operation, not full GUI operation.)

Since there is no GUI, NetLogo primitives which send output to the command center or output area now go to standard output. export-world can still be used to save snapshots of model's state. The report() method is useful for getting results out of the model and into your Java code.

You can make multiple instances of HeadlessWorkspace and they will operate independently on separate threads without interfering with each other.

When running headless, there are some restrictions:

Plotting primitives are non-functional. (However, calling them will not produce any ill effects.)
export-graphics and the movie-* primitives are not available; trying to use them will cause a Java exception.
user-* primitives which query the user for input, such as user-yes-or-no will cause a Java exception.
Sliders, switches, and choosers do not enforce constraints on the values they accept. For example, in the full NetLogo application, if you try to set a switch to a value other than true or false, the switch will not accept the new value. Similarly, a chooser enforces that its value is a valid choice, and a slider enforces that its value is permitted by its minimum, maximum, and increment. When running headless, none of these checks occur.

We plan to lift these restrictions in a future version of NetLogo.

The NetLogo API Specification contains further details.

Other Options

When your program controls NetLogo using the App class, the entire NetLogo application is present, including tabs, menubar, and so forth. This arrangement is suitable for controlling or "scripting" a NetLogo model, but not ideal for embedding a NetLogo model in a larger application.

We also have a separate, similar API which allows embedding only parts of NetLogo, such as only the tabs (not the whole window), or only the contents of the Interface tab. At present, this additional API is not documented. If you are interested in using it, please contact us at feedback@ccl.northwestern.edu.

Conclusion

Don't forget to consult the NetLogo API Specification for full details on these classes and methods.

As mentioned before, the controlling facility is considered experimental. This initial API doesn't necessarily include everything you might expect. Some facilities exist, but are not yet documented. So if you don't see the capability you want, contact us; we may be able to help you do you what you want. Please do not hesitate to contact us at feedback@ccl.northwestern.edu with questions, as we may be able to find a workaround or provide additional guidance where our documentation is thin.