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)

  ## S3 method for class 'list,list,list,list,list,data.frame,data.frame,character':
simInit(times,
  params, modules, objects, paths, inputs, outputs, loadOrder)
## S3 method for class 'ANY,ANY,ANY,character,ANY,ANY,ANY,ANY':
simInit(times, params,
  modules, objects, paths, inputs, outputs, loadOrder)
## S3 method for class 'ANY,ANY,character,ANY,ANY,ANY,ANY,ANY':
simInit(times, params,
  modules, objects, paths, inputs, outputs, loadOrder)
## S3 method for class 'ANY,ANY,ANY,ANY,ANY,ANY,ANY,ANY':
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

objects

An optional list of data objects to be passed into the simList.

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 (nu

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 (nu

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

Examples

Run this code

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
 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 = 3,
     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

Run the code above in your browser using DataCamp Workspace