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.
Caution! The controlling facility is still in an early stage of development. Therefore it is considered "experimental". It is likely to continue to change and grow. Code you write using it now may need changes in order to continue to work in future NetLogo versions.
The NetLogo API Specification contains further details.
Here is a small but complete program that starts NetLogo, opens a model, moves a slider, and runs the model for a few seconds:
import org.nlogo.app.App;
import org.nlogo.compiler.CompilerException;
import java.awt.EventQueue;
public class Example {
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("setup");
for(int i=0; i<50; i++) {
App.app.command("go");
}
}
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.
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.
We are also working on making it possible to run NetLogo "headless", that is with no GUI at all, but at present this is not possible.
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.