0th

Percentile

##### Run a spatial discrete event simulation

Based on code from chapter 7.8.3 of Matloff (2011): "Discrete event simulation". Here, we implement a simulation in a more modular fashion so it's easier to add submodules 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).

##### Usage
spades(sim, debug = FALSE, progress = NA, cache, .plotInitialTime = NULL, .saveInitialTime = NULL, notOlderThan, ...)
"spades"(sim, debug = FALSE, progress = NA, cache, .plotInitialTime = NULL, .saveInitialTime = NULL, notOlderThan, ...)
"spades"(sim, debug = FALSE, progress = NA, cache, .plotInitialTime = NULL, .saveInitialTime = NULL, notOlderThan, ...)
##### Arguments
sim
A simList simulation object, generally produced by simInit.
debug
Optional logical flag determines whether sim debug info will be printed (default is debug=FALSE).
progress
Logical (TRUE or FALSE show a graphical progress bar), character ("graphical", "text") or numeric indicating the number of update intervals to show in a graphical progress bar.
cache
Logical. If TRUE, then the spades call will be cached. This means that if the call is made again with the same simList, then spades will return the return value from the previous run of that exact same simList. Default FALSE. See Details.
.plotInitialTime
Numeric. Temporarily override the .plotInitialTime parameter for all modules. See Details.
.saveInitialTime
Numeric. Temporarily override the .plotInitialTime parameter for all modules. See Details.
notOlderThan
Date. Passed to SpaDES::cache to update the cache. Default is NULL, meaning don't update the cache. If Sys.time() is provided then, it will force a recache. Ignored if cache is FALSE.
...
Any. Can be used to make a unique cache identity, such as "replicate = 1". This will be included in the SpaDES::cache call, so will be unique and thus spades will not use a cached copy as long as anything passed in ... is unique, i.e., not cached previously.
##### Details

The is the workhorse function in the SpaDES package. It runs simulations by implementing the rules outlined in the simList.

This function gives simple access to two sets of module parameters: .plotInitialTime and with .plotInitialTime. The primary use of these arguments is to temporarily turn off plotting and saving. "Temporary" means that the simList is not changed, so it can be used again with the simList values reinstated. To turn off plotting and saving, use .plotInitialTime = NA or .saveInitialTime = NA. NOTE: if a module did not use .plotInitialTime or .saveInitialTime, then these arguments will not do anything.

If cache is TRUE, this allows for a seamless way to "save" results of a simulation. The user does not have to intentionally do any saving manually. Instead, upon a call to spades in which the simList is identical, the function will simply return the result that would have come if it had been rerun. Use this with caution, as it will return exactly the result from a previous run, even if there is stochasticity internally. Caching is only based on the input simList. See also experiment for the same mechanism, but it can be used with replication.

##### Value

Invisibly returns the modified simList object.

##### Note

The debug option is primarily intended to facilitate building simulation models by the user. Will print additional outputs informing the user of updates to the values of various simList slot components.

##### 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

simInit, SpaDES

experiment for using replication with spades.

##### 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"))
#  )
#
#  # Can turn off plotting, and inspect the output simList instead
#  out <- spades(mySim, .plotInitialTime = NA) # much faster
#  completed(out) # shows completed events
#
#  # use cache -- simInit should generally be rerun each time a spades call is made
#  #   to guarantee that it is identical. Here, run spades call twice, first
#  #   time to establish cache, second time to return cached result
#  for(i in 1:2) {
#    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"))
#    )
#    print(system.time(out <- spades(mySim, cache = TRUE)))
#  }
# ## End(Not run)