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).


  debug = getOption("spades.debug"),
  progress = NA,
  .plotInitialTime = NULL,
  .saveInitialTime = NULL,
  notOlderThan = NULL,
  events = NULL,
  .plots = getOption("spades.plots", NULL),

# S4 method for simList,ANY,ANY,missing
  debug = getOption("spades.debug"),
  progress = NA,
  .plotInitialTime = NULL,
  .saveInitialTime = NULL,
  notOlderThan = NULL,
  events = NULL,
  .plots = getOption("spades.plots", NULL),

# S4 method for ANY,ANY,ANY,logical
  debug = getOption("spades.debug"),
  progress = NA,
  .plotInitialTime = NULL,
  .saveInitialTime = NULL,
  notOlderThan = NULL,
  events = NULL,
  .plots = getOption("spades.plots", NULL),



A list of arguments to passed to spades.


A simList simulation object, generally produced by simInit.


Optional tools for invoking debugging. Supplying a list will invoke the more powerful logging package. See details. Default is to use the value in getOption("spades.debug").


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.


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. See also the vignette on caching for examples.


Numeric. Temporarily override the .plotInitialTime parameter for all modules. See Details.


Numeric. Temporarily override the .plotInitialTime parameter for all modules. See Details.


Date or time. Passed to reproducible::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, i.e., remove old value and replace with new value. Ignored if cache is FALSE.


A character vector or a named list of character vectors. If specified, the simulations will only do the events indicated here. If a named list, the names must correspond to the modules and the character vectors can be specific events within each of the named modules. With the list form, all unspecified modules will run all their events, including internal spades modules, e.g., save, that get invoked with the outputs argument in simInit. See example.


Character. Sets the parameter of this name in all modules. See Plots() for possible values. The parameter is intended to slowly take over from .plotInitialTime as a mechanism to turn on or off plotting. For backwards compatibility, if .plotInitialTime is not set in this spades call, but this .plots is used, two things will happen: setting this without "screen" will turn off all plotting; setting this with "screen" will trigger plotting for any modules that use this parameter but will have no effect on other modules. To get plotting, therefore, it may be necessary to also set .plotInitialTime = start(sim).


Any. Can be used to make a unique cache identity, such as "replicate = 1". This will be included in the 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.


Invisibly returns the modified simList object.


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.


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. See for details.

Caching with SpaDES

There are numerous ways in which Caching can be used within SpaDES. Please see the vignette for many examples. Briefly, functions, events, modules, entire spades calls or experiment calls (see can be cached and mixtures of all of these will work. For functions, simply wrap the call with Cache, moving the original function name into the first argument of Cache. For events or modules, set the module parameters, .useCache, e.g., simInit(..., parameters = list(myModule = list(.useCache = "init"))). This can be set to an event name, which will cache that event, or a logical, which will cache every event in that module. Event and module caching makes most sense when the event or module only runs once, such as an initialization or data preparation event/module. Caching an entire simulation is actually just a function call to simInitAndSpades, for example. So, simply writing Cache(simInitAndSpades, modules = ...) will effectively cache a whole simulation. Finally for experiments, it is just like a function call: Cache(simInitandExperiment, ...). The final way Caching can be done is in experiment or spades, by setting the cache argument.

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 the vignette on caching for examples.


The most powerful way to use debug is to invoke the logging R package. To invoke this, debug must be a list with up to 3 named elements: console, file, and debug. Each of these list elements must be a list (including empty list() for defaults) with the sub-list elements here:

consolelevelThe level, see below, of information shown
fileappendLogical. If TRUE, the default, then log entries are appended to file, if it exists
fileA filename. Defaults to log.txt
levelThe level, see below, of information shown
debugSee possible values below

level can be a number from 0 to 100 or a character string matching one of the values in logging::loglevels. These are hierarchical levels of information passed to the console. Set a lower number for more information and a higher number for less information. Errors in code will be shown if level is set to "ERROR" or 40 or above; warnings in code will be shown if level is set to "WARN" or 30 or above; normal messages in code will be shown if level is set to "INFO" or 20 or above. For consistency with base R messaging, if default level is used, then normal messaging via message will be shown; this means that suppressMessages will work to suppress messaging only when level is set to "INFO" or 20. Some functions in the SpaDES ecosystem may have information at the lower levels, but currently, there are few to none.

debug is specified as a non-list argument to spades or as list(debug = ...), then it can be a logical, a quoted call, a character vector or a numeric scalar (currently 1 or 2) or a list of any of these to get multiple outputs. This will be run at the start of every event. The following options for debug are available. Each of these can also be in a list to get multiple outputs:

TRUEcurrent(sim) will be printed at the start of each event as it runs
a function name (as character string)If a function, then it will be run on the simList, e.g., "time" will run time(sim) at each event.
moduleName (as character string)All calls to that module will be entered interactively
eventName (as character string)All calls that have that event name (in any module) will be entered interactively
c(<moduleName>, <eventName>)Only the event in that specified module will be entered into.
Any other R expression expressed as a character string or quoted callWill be evaluated with access to the simList as sim. If this is more than one character string, then all will be printed to the screen in their sequence.
A numeric scalar, currently 1 or 2 (maybe others)This will print out alternative forms of event information that users may find useful

If not specified in the function call, the package option spades.debug is used.

If options("spades.browserOnError" = TRUE) (experimental still) if there is an error, it will attempt to open a browser in the event where the error occurred. You can edit, and then press c to continue or Q to quit, plus all other normal interactive browser tools. c will trigger a reparse and events will continue as scheduled, starting with the one just edited. There may be some unexpected consequences if the simList objects had already been changed before the error occurred.


Matloff, N. (2011). The Art of R Programming (ch. 7.8.3). San Francisco, CA: No Starch Press, Inc.. Retrieved from

See also

SpaDES.core-package(), simInit(), and the caching vignette (very important for reproducibility): which uses reproducible::Cache().



Alex Chubaty and Eliot McIntire


# \donttest{
if (requireNamespace("", quietly = TRUE) &&
    requireNamespace("NLMR", quietly = TRUE)) {
  # some options are not necessary when not interactive
  opts <- options("spades.moduleCodeChecks" = FALSE, "spades.useRequire" = FALSE)
  if (!interactive()) opts <- append(opts, options("spades.plots" = NA))
  mySim <- simInit(
   times = list(start = 0.0, end = 1.0, timeunit = "year"),
   params = list(
     randomLandscapes = list(nx = 10, ny = 10),
     .globals = list(stackName = "landscape", burnStats = "nPixelsBurned",
                     .plots = NA) # plotting off --> not relevant for example
   modules = list("randomLandscapes", "fireSpread", "caribouMovement"),
   paths = list(modulePath = getSampleModules(tempdir()))

  options(opts) # reset options
#> Setting:
#>   options(
#>     spades.modulePath = '/tmp/Rtmpd0rH1m/sampleModules'
#>   )
#> Paths set to:
#>   options(
#>     rasterTmpDir = '/tmp/Rtmpd0rH1m/scratch/raster'
#>     reproducible.cachePath = '/tmp/Rtmpd0rH1m/cache'
#>     spades.inputPath = '/tmp/Rtmpd0rH1m/inputs'
#>     spades.outputPath = '/tmp/Rtmpd0rH1m'
#>     spades.modulePath = '/tmp/Rtmpd0rH1m/sampleModules'
#>     spades.scratchPath = '/tmp/Rtmpd0rH1m/scratch'
#>   )
#>   terra::terraOptions(tempdir = '/tmp/Rtmpd0rH1m/scratch/terra'
#> Jun07 03:22:17 simInit Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Jun07 03:22:17 simInit The following .globals were used:
#> Jun07 03:22:17 simInit Key: <global, module>
#> Jun07 03:22:17 simInit module    global
#> Jun07 03:22:17 simInit <char>    <char>
#> Jun07 03:22:17 simInit 1:  caribouMovement    .plots
#> Jun07 03:22:17 simInit 2:       fireSpread    .plots
#> Jun07 03:22:17 simInit 3: randomLandscapes    .plots
#> Jun07 03:22:17 simInit 4:  caribouMovement stackName
#> Jun07 03:22:17 simInit 5:       fireSpread stackName
#> Jun07 03:22:17 simInit 6: randomLandscapes stackName
#> Elpsed time for simInit: 0.09651065 secs
#> Jun07 03:22:17 simInit Using setDTthreads(1). To change: 'options(spades.DTthreads = X)'.
#> Jun07 03:22:17 chckpn:init total elpsd: 0.098 secs | 0 checkpoint init 0
#> Jun07 03:22:17 save  :init total elpsd: 0.1 secs | 0 save init 0
#> Jun07 03:22:17 prgrss:init total elpsd: 0.1 secs | 0 progress init 0
#> Jun07 03:22:17 load  :init total elpsd: 0.1 secs | 0 load init 0
#> Jun07 03:22:17 rndmLn:init total elpsd: 0.11 secs | 0 randomLandscapes init 1
#> Jun07 03:22:17 rndmLn:init New objects created:
#> Jun07 03:22:17 rndmLn:init        <char>
#> Jun07 03:22:17 rndmLn:init 1:  landscape
#> Jun07 03:22:17 frSprd:init total elpsd: 0.24 secs | 0 fireSpread init 1
#> Jun07 03:22:17 frSprd:init fireSpread
#> Jun07 03:22:17 frSprd:init New objects created:
#> Jun07 03:22:17 frSprd:init           <char>
#> Jun07 03:22:17 frSprd:init 1: nPixelsBurned
#> Jun07 03:22:17 crbMvm:init total elpsd: 0.26 secs | 0 caribouMovement init 1
#> Jun07 03:22:17 crbMvm:init New objects created:
#> Jun07 03:22:17 crbMvm:init        <char>
#> Jun07 03:22:17 crbMvm:init 1:    caribou
#> Jun07 03:22:17 frSprd:burn total elpsd: 0.27 secs | 1 fireSpread burn 5
#> Jun07 03:22:17 crbMvm:move total elpsd: 0.29 secs | 1 caribouMovement move 5
#> Jun07 03:22:17 crbMvm:move New objects created:
#> Jun07 03:22:17 crbMvm:move            <char>
#> Jun07 03:22:17 crbMvm:move 1: habitatQuality
#> Jun07 03:22:17 frSprd:stats total elpsd: 0.31 secs | 1 fireSpread stats 5
#> Jun07 03:22:17 frSprd:stats fireSpread
#> simList saved in
#> SpaDES.core:::savedSimEnv()$.sim
#> It will be deleted at next spades() call.
# }