RNetLogo (version 0.9.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, obj.name=NULL, nl.version=5, is3d=FALSE)

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 5.0.3".

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.

obj.name

(optional) A string with the name of a variable which will contain the reference to the NetLogo instance. After NLStart is finished, there will be a variable with the given name in the global scope. This variable is needed for all oth

nl.version

(optional) An integer value specifying the (major) version of NetLogo being started. Don't try to start a NetLogo version 4.x with nl.version=5 and vice versa. It is not possible to mix NetLogo versions in one R session. Please use different R sessi

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 Net

Value

• The function implicitly returns a Java Object containing the reference to the Java controlling interface, stored in a variable with the name given in the third argument.

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 and reporters. In GUI mode you can execute commands and reporters already with the inital empty model without loading a specific one.

Details

You can start multiple instances of NetLogo in headless mode and save each in another variable 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 http://cran.r-project.org/web/packages/JGR/index.html 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 http://cran.r-project.org/web/packages/JGR/index.html). 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 (see description here: https://stat.ethz.ch/pipermail/r-devel/2013-January/065576.html). The reason could be the increased C stack size since 2.15.2. If you execute Cstack_info() you can see how large the C stack size is. A workaround is to use R 2.15.1 or to start RNetLogo from JGR (see http://cran.r-project.org/web/packages/JGR/index.html) 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 when submitting NLQuit (doesn't work currently with custom obj.name). As mentioned in NLQuit, it is currently not possible to quit NetLogo completly. 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 could 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 http://permalink.gmane.org/gmane.comp.lang.r.rosuda.devel/1284. See the directory examples in the installation directory of the package for example codes to all RNetLogo functions. See the document tutorial.pdf 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.

See Also

NLQuit

Examples

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

# create a second NetLogo instance in headless mode (= without GUI) 
# with explicit name of stored object
NLStart(nl.path, FALSE, "nlheadless1")
model.path <- "/models/Sample Models/Earth Science/Fire.nlogo"
NLLoadModel(paste(nl.path,model.path,sep=""), 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
NLStart(nl.path, FALSE, "nlheadless2")
model.path <- "/models/Sample Models/Earth Science/Fire.nlogo"
NLLoadModel(paste(nl.path,model.path,sep=""), nlheadless2)
NLCommand("setup", nl.obj=nlheadless2)
burned2 <- NLDoReport(10, "go", c("ticks","burned-trees"), 
                      as_dataframe=TRUE,dfcolnames=c("tick","burned"), 
                      nl.obj=nlheadless2)
print(burned2)