SpaDES (version 1.2.0)

simInit: Initialize a new simulation

Description

Create a new simulation object, the "sim" object. This object is implemented using an environment where all objects and functions are placed. Since environments in R are pass by reference, "putting" objects in the sim object does no actual copy. This is also the location of all parameters, and other important simulation information, such as times, paths, modules, and module load order. See more details below.

Usage

simInit(times, params, modules, objects, paths, inputs, outputs, loadOrder)
 "simInit"(times, params, modules, objects, paths, inputs, outputs, loadOrder)
"simInit"(times, params, modules, objects, paths, inputs, outputs, loadOrder)
"simInit"(times, params, modules, objects, paths, inputs, outputs, loadOrder)
"simInit"(times, params, modules, objects, paths, inputs, outputs, loadOrder)

Arguments

times

A named list of numeric simulation start and end times (e.g., times = list(start = 0.0, end = 10.0)).

params

A list of lists of the form list(moduleName=list(param1=value, param2=value)). See details.

modules

A named list of character strings specfying the names of modules to be loaded for the simulation. Note: the module name should correspond to the R source file from which the module is loaded. Example: a module named "caribou" will be sourced form the file ‘caribou.R’, located at the specified modulePath(simList) (see below).

objects

(optional) A vector of object names (naming objects that are in the .GlobalEnv), or a named list of data objects to be passed into the simList. These objects will be accessible from the simList as a normal list, e.g,. mySim$obj.

paths

An optional named list with up to 4 named elements, modulePath, inputPath, outputPath, and cachePath. See details.

inputs

A data.frame. Can specify from 1 to 6 columns with following column names: objectName (character, required), file (character), fun (character), package (character), interval (numeric), loadTime (numeric). See inputs and vignette("ii-modules") section about inputs.

outputs

A data.frame. Can specify from 1 to 5 columns with following column names: objectName (character, required), file (character), fun (character), package (character), saveTime (numeric). See outputs and vignette("ii-modules") section about outputs.

loadOrder

An optional list of module names specfiying the order in which to load the modules. If not specified, the module load order will be determined automatically.

Value

A simList simulation object, pre-initialized from values specified in the arguments supplied.

Details

Calling this simInit function does several things including the following: - sources all module files, placing all function definitions in the sim object - optionally copies objects from the global environment to the sim object - optionally loads objects from disk - schedules all "init" events from all modules - assesses module dependencies via the inputs and outputs identified in their metadata - determines time units of modules and how they fit together

params can only contain updates to any parameters that are defined in the metadata of modules. Take the example of a module named, Fire, which has a parameter named .plotInitialTime. In the metadata of that moduel, it says TRUE. Here we can override that default with: list(Fire=list(.plotInitialTime=NA)), effectively turning off plotting. Since this is a list of lists, one can override the module defaults for multiple parameters from multiple modules all at once, with say: list(Fire=list(.plotInitialTime=NA, .plotInterval=2), caribouModule=list(N=1000)).

We implement a discrete event simulation in a more modular fashion so it is easier to add modules to the simulation. We use S4 classes and methods, and use data.table instead of data.frame to implement the event queue (because it is much faster).

paths specifies the location of the module source files, the data input files, and the saving output files. If no paths are specified, default is current working directory.

References

Matloff, N. (2011). The Art of R Programming (ch. 7.8.3). San Fransisco, CA: No Starch Press, Inc.. Retrieved from https://www.nostarch.com/artofr.htm

See Also

spades, times, params, objs, paths, modules, inputs, outputs

Examples

## Not run: 
#  mySim <- simInit(
#    times = list(start = 0.0, end = 2.0, timeunit = "year"),
#    params = list(
#      .globals = list(stackName = "landscape", burnStats = "nPixelsBurned")
#    ),
#    modules = list("randomLandscapes", "fireSpread", "caribouMovement"),
#    paths = list(modulePath = system.file("sampleModules", package = "SpaDES"))
#  )
#  spades(mySim)
# 
#  # Change more parameters, removing plotting
#  wantPlotting <- FALSE
#  mySim <- simInit(
#    times = list(start = 0.0, end = 2.0, timeunit = "year"),
#    params = list(
#      .globals = list(stackName = "landscape", burnStats = "nPixelsBurned"),
#      fireSpread = list(.plotInitialTime=wantPlotting),
#      #caribouMovement = list(.plotInitialTime=wantPlotting),
#      #randomLandscapes = list(.plotInitialTime=wantPlotting)
#    ),
#    modules = list("randomLandscapes", "fireSpread", "caribouMovement"),
#    paths = list(modulePath = system.file("sampleModules", package = "SpaDES"))
#  )
#  outSim <- spades(mySim)
# 
# # A little more complicated with inputs and outputs
# if (require(rgdal)) {
#    mapPath <- system.file("maps", package = "SpaDES")
#    mySim <- simInit(
#      times = list(start = 0.0, end = 2.0, timeunit = "year"),
#      params = list(
#        .globals = list(stackName = "landscape", burnStats = "nPixelsBurned")
#      ),
#      modules = list("randomLandscapes", "fireSpread", "caribouMovement"),
#      paths = list(modulePath = system.file("sampleModules", package = "SpaDES"),
#                   outputPath = tempdir()),
#      inputs = data.frame(
#        files = dir(file.path(mapPath), full.names = TRUE, pattern = "tif")[1:2],
#        functions = "raster",
#        package = "raster",
#        loadTime = 0,
#        stringsAsFactors = FALSE),
#      outputs = data.frame(
#        expand.grid(objectName = c("caribou","landscape"),
#        saveTime = 1:2,
#        stringsAsFactors = FALSE))
#    )
# 
#    # Use accessors for inputs, outputs, times
#    mySim2 <- simInit(modules = list("randomLandscapes", "fireSpread",
#                                     "caribouMovement"),
#                      params = list(.globals = list(stackName = "landscape",
#                                                    burnStats = "nPixelsBurned")),
#                      paths = list(modulePath = system.file("sampleModules",
#                                                            package = "SpaDES"),
#                                   outputPath = tempdir()))
#    # add by accessor: note need current in times() accessor
#    times(mySim2) <- list(current=0, start = 0.0, end = 2.0, timeunit = "year")
#    inputs(mySim2) <- data.frame(
#        files = dir(file.path(mapPath), full.names = TRUE, pattern = "tif")[1:2],
#        functions = "raster",
#        package = "raster",
#        loadTime = 3,
#        stringsAsFactors = FALSE)
#    outputs(mySim2) <- data.frame(
#        expand.grid(objectName = c("caribou","landscape"),
#        saveTime = 1:2,
#        stringsAsFactors = FALSE))
#    all.equal(mySim, mySim2) # TRUE
#   }
# ## End(Not run)