RNetLogo (version 1.0-4)

NLStart: Creates an instance of NetLogo

Description

NLStart creates a new instance of NetLogo in either headless (without the Graphical User Interface) or GUI mode.

Usage

NLStart(nl.path, gui=TRUE, nl.obj=NULL, is3d=FALSE, nl.jarname='netlogo-6.0.0.jar')

Arguments

nl.path

An absolute path to your NetLogo installation (the folder where the NetLogo.jar is) starting from the root. On Windows, for example, something like "C:/Program Files/NetLogo 6.0/app".

gui

(optional) A boolean value: if TRUE, NetLogo will be started with GUI (only one instance with GUI can be created currently!). FALSE will start NetLogo in headless mode.

nl.obj

(optional) A string which is used to identify the created NetLogo instance reference internally (in .rnetlogo environment). To refer to this instance just use the same name in the other functions of this package. If nl.obj=NULL (default), the internal name to the reference is _nl.intern_ and is not needed to be submitted to the other functions of this package. After using NLQuit, the identical name can be used again for a new instance.

is3d

(optional) A boolean value: if TRUE, NetLogo 3D will be started. FALSE will start the conventional 2D NetLogo. This functionality is experimental. All RNetLogo functions should work in NetLogo 3D as they do in conventional 2D NetLogo except NLSetPatches, which is currently not implemented to work in NetLogo 3D properly.

nl.jarname

(optional) The name of the NetLogo jar file. Since NetLogo 6.0 the jar file includes the version number. Default value is netlogo-6.0.0.jar. For other version the name has to be set here.

Value

No return value.

Warning

It's not possible to run multiple instances of NetLogo in GUI mode! Closing NetLogo from the NetLogo Window is blocked, because it would quit the whole R process. To close the NetLogo call NLQuit. If you use the headless mode you should first load a model with NLLoadModel before executing other commands or reporters. In GUI mode you can execute commands and reporters already with the initial empty model without loading a specific one.

Details

You can start multiple instances of NetLogo in headless mode and store each in another variable (using nl.obj) but it is not possible to start multiple instances in GUI mode. (It would result in an crash of R since there is no way to detach the Java Virtual Machine via rJava.) But there is a trick to run RNetLogo in GUI mode multiple times described in the document parallelProcessing.pdf in directory parallelProcessing in the installation directory of the package.

Note for Mac OS users: If you want to run RNetLogo in headless mode (without GUI, i.e. setting argument gui=FALSE) you have to disable AWT before loading the package. Just execute Sys.setenv(NOAWT=1) before executing library(RNetLogo). If you want to run RNetLogo in GUI mode you have to start it from the JGR application (see https://cran.r-project.org/package=JGR and the note at http://groups.yahoo.com/group/netlogo-users/message/14817). It can be necessary to run Sys.setenv(NOAWT=1) before loading the JGR package and run Sys.unsetenv("NOAWT") before starting JGR via JGR().

Note for Linux users: If you want to run RNetLogo in GUI mode you should start RNetLogo in the JGR application (see https://cran.r-project.org/package=JGR).

Note for Windows 32-bit users: Starting RNetLogo (in GUI mode) on 32-bit Windows (not 64-bit Windows running in 32-bit mode) may fail in R version 2.15.2 and 2.15.3 (see description here: https://stat.ethz.ch/pipermail/r-devel/2013-January/065576.html). The reason could be the increased C stack size in 2.15.2 and 2.15.3. If you execute Cstack_info() you can see how large the C stack size is. The problem seems to be resolved with 3.0.0. A workaround is to use R 2.15.1 or 3.x or to start RNetLogo from JGR (see https://cran.r-project.org/package=JGR) or RStudio (see http://www.rstudio.com/).

Avoid manually changing the working directory of R, because NetLogo needs to have the working directory pointed to its installation path. As the R working directory and the Java working directory depend on each other, changing the R working directory can result in unexpected behavior of NetLogo. Therefore, you should use absolute paths for I/O processes in R instead of submitting setwd(...). Note that the RNetLogo package changes the working directory automatically when loading NetLogo and changes back to the former working directory closing the last active instance of NetLogo with NLQuit.

As mentioned in NLQuit, it is currently not possible to quit NetLogo completely.

If you want to specify options for the underlying Java Virtual Machine (JVM), like increasing the Java Heap Space for large models, execute options(java.parameters="...") before loading the RNetLogo package with library(RNetLogo) or require(RNetLogo). For increasing the Java Heap Space it can be options(java.parameters="-Xmx1024m"), for example. Use a vector of strings for setting multiple options, for example options(java.parameters=c("-server","-Xmx1300m")). See also http://ccl.northwestern.edu/netlogo/docs/faq.html#howbig and rJava manual.

See the directory examples in the installation directory of the package for example codes to all RNetLogo functions.

See Thiele (2014) (also included in directory tutorial in the installation directory of the package) for a step-by-step usage tutorial.

See the vignette performanceNotes.pdf for performance notes.

See the vignette parallelProcessing.pdf on how to run RNetLogo on multiple processors/clusters in parallel.

References

Thiele, J. (2014) R Marries NetLogo: Introduction to the RNetLogo Package. Journal of Statistical Software 58(2) 1-41. http://www.jstatsoft.org/v58/i02/

See Also

NLQuit

Examples

library(RNetLogo)
nl.path <- "C:/Program Files/NetLogo 6.0/app"
NLStart(nl.path)
NLCommand("create-turtles 10")
noturtles <- NLReport("count turtles")
print(noturtles)

# create a second NetLogo instance in headless mode (= without GUI) 
# stored in a variable
nlheadless1 <- "nlheadless1"
NLStart(nl.path, gui=F, nl.obj=nlheadless1)
model.path <- "/models/Sample Models/Earth Science/Fire.nlogo"
NLLoadModel(paste(nl.path,model.path,sep=""), nl.obj=nlheadless1)
NLCommand("setup", nl.obj=nlheadless1)
burned1 <- NLDoReport(20, "go", c("ticks","burned-trees"), 
                      as.data.frame=TRUE,df.col.names=c("tick","burned"), 
                      nl.obj=nlheadless1)
print(burned1)

# create a third NetLogo instance in headless mode (= without GUI) 
# with explicit name of stored object
nlheadless2 <- "nlheadless2"
NLStart(nl.path, gui=F, nl.obj=nlheadless2)
model.path <- "/models/Sample Models/Earth Science/Fire.nlogo"
NLLoadModel(paste(nl.path,model.path,sep=""), nl.obj=nlheadless2)
NLCommand("setup", nl.obj=nlheadless2)
burned2 <- NLDoReport(10, "go", c("ticks","burned-trees"), 
                      as.data.frame=TRUE,df.col.names=c("tick","burned"), 
                      nl.obj=nlheadless2)
print(burned2)